DocsGuidesError handling & retries

Error handling & retries

Branch on status codes and retry with exponential backoff to survive rate limits and upstream hiccups.

Two rules: branch on the HTTP status and the error type/status field (messages are localized — matching text will break), and retry only what's worth retrying — a malformed request never becomes valid by repetition.

What to do per status code

HTTP	Typical cause	Action
400	Malformed body, missing fields	Fix the request. Do not retry.
401 / 403	Key invalid/disabled, IP blocked	Check the key and its config. Do not retry.
402	Balance or key quota exhausted	Top up or raise the limit. Do not auto-retry — the outcome won't change.
404	Unknown model / unsupported endpoint	Check ids against Models.
413	Payload too large	Compress inlined media or switch endpoints. Do not retry.
429	RPM/concurrency limit	Retry with exponential backoff + jitter.
502 / 503	Upstream failure / gateway overloaded	Retry with backoff; the gateway itself already attempts failover first.

Exponential backoff example

retry.py

import random
import time

from openai import OpenAI, APIStatusError

client = OpenAI(api_key="sk-sole-...", base_url="https://api.soleapi.com/v1")

RETRYABLE = {429, 502, 503}

def create_with_retry(**kwargs):
    delay = 1.0
    for attempt in range(5):
        try:
            return client.responses.create(**kwargs)
        except APIStatusError as e:
            if e.status_code not in RETRYABLE or attempt == 4:
                raise
            time.sleep(delay + random.random())  # jitter
            delay = min(delay * 2, 30)

The official OpenAI and Anthropic SDKs already auto-retry 429/5xx (see max_retries) — usually that's all you need. If you roll your own, always add jitter so many clients don't retry in lockstep.

Troubleshooting tips

Log the full error body and timestamp: the type/status field plus the HTTP status pinpoint the category — see Errors.
Sporadic 5xx is normal jitter; investigate only if it persists. The console's request logs let you cross-reference every failed call.
For frequent 429s, lower your concurrency first, then ask the administrator about limits — see Rate limits & quotas.