Errors

Errors come back as JSON with an error object, in the shape the OpenAI SDKs expect. The HTTP status tells you what class of problem it is; the code tells you which one.

1{
2  "error": {
3    "message": "You are out of credits.",
4    "type": "billing_error",
5    "code": "insufficient_credits",
6    "param": null,
7    "request_id": "req_9a2f..."
8  }
9}

Status codes#

Error types#

The codes you will actually meet#

Bad requests

• unknown_model — the id is not one of the three. OpenAI model names land here.
• media_not_supported — you attached an image to Bala, or video to anything but Rishi.
• model_generation_unsupported — you asked a model to generate media it cannot.
• context_window_exceeded — your messages are longer than the model’s window.
• conflicting_parameters — you sent both max_tokens and max_completion_tokens. Send one.
• invalid_tool_arguments — a tool call in your message history has arguments that are not valid JSON.
• unsupported_parameter — a field we deliberately reject; the message names the replacement.

Billing

A 402 carries extra fields so you can render a useful prompt rather than a dead end.

1{
2  "error": {
3    "message": "You are out of credits.",
4    "type": "billing_error",
5    "code": "insufficient_credits",
6    "balance": 0,
7    "action": "add_credits",
8    "action_label": "Add credits",
9    "action_url": "https://upfyn.com/dashboard/ai/billing"
10  }
11}

• insufficient_credits — balance is exhausted.
• no_active_plan — the account has no plan.
• daily_spend_limit_exceeded — a cap you set was reached; it clears at the next window.

Rate limits

• user_rate_limit_exceeded — the account’s per-minute request limit.
• key_rate_limit_exceeded — that one key’s limit.
• temporary_auto_block — repeated 429s triggered a short cool-off. Back off properly rather than retrying harder.

Rate limits has the numbers and the headers.

Errors during a stream#

Once a stream has started, the response is already committed to 200 — the status cannot change. A failure therefore arrives as a frame in the stream, followed by the usual terminator.

1data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"The answer is"}}]}
2 
3data: {"error":{"message":"Upstream failed.","type":"server_error","code":"upstream_stream_error"}}
4 
5data: [DONE]

Retrying well#

Retry 429, 500 and 503. Never retry 400, 401, 402 or 403 — they will fail identically and a retry loop on a 402 is just noise. Honour Retry-After when it is present.

1import time, random
2from openai import OpenAI, APIStatusError
3 
4client = OpenAI(base_url="https://ai.upfyn.com/v1", api_key=KEY)
5 
6RETRYABLE = {429, 500, 502, 503, 504}
7 
8def complete(**kwargs):
9    for attempt in range(5):
10        try:
11            return client.chat.completions.create(**kwargs)
12        except APIStatusError as err:
13            if err.status_code not in RETRYABLE:
14                raise                      # 400/401/402/403 will never succeed on retry
15            wait = float(err.response.headers.get("Retry-After") or 0)
16            if not wait:
17                wait = (2 ** attempt) + random.random()   # backoff with jitter
18            time.sleep(wait)
19    raise RuntimeError("gave up after 5 attempts")