Errors

Every error is JSON with one error object, the same shape OpenAI uses plus a request_id:

{
  "error": {
    "message": "model \"gpt-4o\" does not exist",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model",
    "request_id": "0192a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
  }
}

type is one of seven values and tells you what kind of problem it is. code is a stable, machine-readable detail. param names the offending field or is null. request_id matches the X-Request-Id response header, which siema_ai always generates itself — a client-sent X-Request-Id is ignored, not echoed.

HTTP	type	code	Cause	Retry?
400	invalid_request_error	invalid_json	Body is not valid JSON.	No
400	invalid_request_error	invalid_request	Missing or out-of-range field (param says which); a body over the 20 MiB default limit; an alias used for a capability it doesn’t have (for example chat on embed); max_tokens less than 1; or the model server rejecting a forwarded field.	No
400	invalid_request_error	context_length_exceeded	Prompt plus max_tokens exceeds context_length.	No, shorten the input
401	authentication_error	invalid_api_key	Missing, malformed, unknown or revoked key.	No
402	insufficient_quota	insufficient_quota	Prepaid balance is not positive.	No, top up first
403	permission_error	org_suspended	Organisation suspended.	No, contact support
404	invalid_request_error	model_not_found	Unknown alias.	No
404	invalid_request_error	unsupported_endpoint	An OpenAI endpoint siema_ai does not offer, or the right endpoint called with the wrong HTTP method. Calling one without an API key returns 401 first.	No
429	rate_limit_error	rate_limit_exceeded	Per-key requests per minute exceeded.	After Retry-After
429	rate_limit_error	concurrency_limit_exceeded	Too many in-flight requests for the organisation.	After Retry-After
500	server_error	internal_error	Gateway bug, outage, or the organisation’s balance could not be checked.	Yes, with backoff
502	upstream_error	upstream_unavailable	Every deployment of the model failed before the first byte, the model server answered a 4xx other than 400, or its reply exceeded 64 MiB.	Yes, with backoff
502	upstream_error	upstream_timeout	No first byte within 180 s (after the one automatic failover); on a non-streaming reply, a gap between chunks over 60 s once the reply has started; or the attempt exceeded the 600 s total budget. On a stream, an idle gap after the first byte ends the stream without [DONE] instead of a 502 — see Streaming.	Yes, with backoff
503	server_error	no_capacity	A known alias has no capacity right now, or the gateway’s routing table has not loaded yet.	Yes, with backoff

What a failed request costs

Anything rejected before it reaches a model server — 400, 401, 402, 403, 404, 429, 503, and a 500 from an internal failure such as a balance check that couldn’t complete — costs nothing. A 502 that happens before the model server sends any reply — a connection failure, a first-byte timeout, or an upstream 4xx/5xx before the first byte — also costs nothing. A non-streaming request that fails after the model server started sending its reply is charged the estimated input tokens, and so is a client disconnect at any point after the gateway sent your request upstream, including during a cold start before any reply has begun. If you disconnect only after the model’s full reply had already reached the gateway — it just couldn’t be written back to you — you’re charged the full usage for that reply, not an estimate. A stream that fails partway through, including one you disconnect yourself, is charged for the tokens produced up to that point, using an estimate; see Billing and Streaming.

The OpenAI SDKs retry 408, 409, 429 and 5xx automatically (twice by default) and never retry 402.

Why 402 and not 429 for an empty balance

OpenAI reports an exhausted quota as HTTP 429 with type insufficient_quota. Official SDKs retry 429 automatically with backoff, which for a quota error just delays the failure by a minute and burns your rate limit. siema_ai returns 402 instead: SDKs raise it immediately as an API status error. Detect it by status code or by error.type == "insufficient_quota", and point the user at the top-up page. Nothing is billed for a 402.

from openai import APIStatusError

try:
    r = client.chat.completions.create(model="polish-pro", messages=msgs)
except APIStatusError as e:
    if e.status_code == 402:
        notify_billing_owner()
    else:
        raise

Streaming errors

Errors before the first byte use the statuses above. Once the response has started, the HTTP status is already 200; a failure there ends the connection without data: [DONE] and without any in-band error event — see Streaming for how to detect it.

Including the request id in support requests

Email support@siema-ai.pl with the request_id. We can see the model, timing, token counts and status of that request. We cannot see the prompt or the answer.