Errors & retries

Error response format

All errors return JSON, identical in shape to OpenAI:

json
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit reached. Please retry after 12s.",
    "param": null
  }
}

Status-code cheat-sheet

Retry strategy

General rules:

• Don't retry 4xx (except 408, 429).
• Always retry 5xx.
• Max 3 attempts. Beyond that, let it bubble up to caller logic.
• Exponential back-off + jitter: 1s → 2s → 4s with ±20% jitter to avoid synchronised retry stampedes.
• Respect Retry-After: when 429 / 503 carry the header, wait the duration it specifies.

python
import time, random
from openai import OpenAI, APIError, RateLimitError

client = OpenAI(api_key="<KEY>", base_url="https://api.aicodedog.com/v1")

def chat_with_retry(**kwargs):
    last_err = None
    for attempt in range(3):
        try:
            return client.chat.completions.create(**kwargs)
        except RateLimitError as e:
            wait = (2 ** attempt) * (1 + random.uniform(-0.2, 0.2))
            time.sleep(wait)
            last_err = e
        except APIError as e:
            if e.status_code and 500 <= e.status_code < 600:
                wait = (2 ** attempt) * (1 + random.uniform(-0.2, 0.2))
                time.sleep(wait)
                last_err = e
            else:
                raise  # 4xx is not recoverable
    raise last_err

Context too long

If your messages + max_tokens exceed the model's context window, you immediately get 400 with code: "context_length_exceeded".

• Short term: truncate history (keep the system message + recent N turns).
• Medium term: swap to a longer-context model like Kimi-K2.6 (200K) or claude-opus-4-1 (200K).
• Long term: move to RAG (see Embeddings) — chunk and index long documents, retrieve on demand.