Errors

Quick

The whole decision table. The detail behind each row is in the sections below.

No refusal is fixed by retrying immediately. A client that treats every error as "try again now" spends its whole allowance on being refused.

The refusal envelope

A refused call answers with one JSON object carrying a single error member. It is this protocol's own envelope and not a translation of another's: the same shape refuses a Chat Completions call, a Responses call and a Messages call, and the Messages surface wraps it with the top-level "type": "error" its own clients look for.

Two members are always present — type and message — and two more appear when there is something to say.

Branch on type and on code, never on the wording of message: the wording is chosen to be safe to print, not to be parsed.

{
  "error": {
    "type": "authentication_error",
    "message": "The request is not authenticated."
  }
}

Status codes

Two of them are worth telling apart before you write a retry. A 429 is a ceiling you are over, and time is what clears it; a 503 means nothing upstream can serve the call at this moment. Neither is fixed by retrying at once, and a client that treats every refusal as "try again immediately" spends its whole allowance on being refused.

One 401, whatever is wrong with the key

A missing key, a malformed key, an unknown key, a revoked key and an expired key are answered alike — the same 401, the same sentence — and that is a decision rather than an omission. Telling them apart would turn the gateway into an oracle over key material: whoever can see the difference between "there is no such key" and "that key was revoked" is reading the platform's key table one guess at a time.

So a 401 says exactly one thing: this call was not admitted. Check that the header is there and spelled as a bearer token, that the key is the whole secret you copied when you minted it, and that the key is still live. The key check answers all three at once, from a browser, without a line of code.

Check your key → How the header is written →

A stream that stops early

A refusal decided before the first event is an ordinary JSON error with a status, exactly as a unary call would be — the envelope above, and nothing streamed. A failure after the stream has started cannot be that: the status line has already gone out. Such a stream simply ends, without its terminal [DONE] frame.

That absence is the whole signal, so read for it. A client that treats "the connection closed" as "the answer finished" will hand a truncated answer to whatever comes next, and nothing in the bytes it received says otherwise. Treat a stream that ends before [DONE] as a failed call rather than a short one.

The other two surfaces say the same thing in their own events. On the Messages surface the failure arrives as this protocol's error event and the stream then ends without message_stop; on the Responses surface the terminal event is response.failed, carrying this envelope in place of the finished body.

Failover

A model is usually reachable through more than one channel. When the one serving a call fails before any of the answer has reached you, the call carries on over the next channel for the same model rather than coming back to you.

Three kinds of failure end the call instead of moving it: a failure after the first bytes have reached you, because you cannot be handed a second answer halfway through one you are already reading; a call you canceled, because you are no longer waiting for it; and a call whose outcome upstream is not known, because retrying that one could bill you twice for work that in fact succeeded.

So a 503 is not a promise that every route was tried. It also arrives when no channel is eligible for what the call asked for, before anything upstream is contacted at all, and the number of channels a single call will try is bounded rather than exhaustive.

What bounds your throughput →