Errors and retries
SayGM returns the error envelope native to the compatibility surface where possible. Use the HTTP status first, then inspect the structured error body.
| Status | Typical meaning | Retry? |
|---|---|---|
400 |
Invalid or unsupported request | No; change the request. |
401 |
Missing or invalid API key | No; replace or fix the key. |
402 |
Insufficient prepaid credit | No; add credit first. See insufficient credit for the surface envelope. |
404 |
GET /v1/models/{id} for a model not in the catalog |
No; choose another model. |
429 |
Rate or capacity limit | Yes, with backoff. |
500 |
Unexpected gateway or upstream failure | Usually, with a bounded retry. |
502 / 503 |
Upstream or routing availability failure | Yes, with backoff or another model. |
504 |
Upstream timeout | Yes, but account for possible prior processing. |
Error body
Section titled “Error body”On OpenAI-compatible routes the body wraps a single error object. A request
sent without a usable API key returns HTTP 401 and:
{ "error": { "message": "Invalid Authentication", "type": "invalid_request_error", "code": "invalid_api_key", "param": null }}Retrieving GET /v1/models/{id} for a model that is not in the public catalog
returns HTTP 404 and the same envelope with "code": "model_not_found". An
inference request that names an unknown model, or a model the surface does not
serve, returns HTTP 400.
Requests using the routing headers can also fail with 400
for an invalid header or a provider restriction no route can meet, and with
503 when the allowed providers cannot serve right now.
Branch on error.code, not on error.message. Message text is written for
humans and can change; param is populated only when a specific request field
caused the failure.
Insufficient credit
Section titled “Insufficient credit”HTTP 402 means your credit could not cover the request. The
request settlement section explains
the balance check and how the output limit may be lowered first.
The response uses the envelope for the called API surface:
| Surface | Error fields |
|---|---|
| OpenAI-compatible Chat Completions or Responses | error.type and error.code are both insufficient_quota. |
| Anthropic Messages | Top-level type is error, error.type is permission_error, and the body includes request_id. |
| Gemini | error.code is HTTP 402 and error.status is PERMISSION_DENIED. |
An empty list is not an error
Section titled “An empty list is not an error”Filtering the catalog with an unrecognized value returns HTTP 200 and an empty
list rather than a 400:
curl -fsSL "https://api.saygm.com/v1/models?api_shape=does-not-exist"{ "object": "list", "data": [] }An unrecognized query parameter name is ignored outright, so the response is the
unfiltered catalog. If your application discovers models at startup, treat an
empty data list as a configuration error and fail loudly. A silent empty
result is otherwise indistinguishable from an outage. Valid api_shape values
are listed under choose a model.
Retry policy
Section titled “Retry policy”For retryable failures:
- Honor
Retry-Afterwhen present. - Use exponential backoff with jitter.
- Cap both attempts and total elapsed time.
- Avoid automatic retries after a streaming response has emitted content.
- Log a request identifier and status, never the API key or sensitive prompt.
Gateway retry behavior
Section titled “Gateway retry behavior”For Messages, Chat Completions, Responses, and Gemini content requests,
the gateway retries upstream 429 and 500–599 responses on another route
within the request’s attempt and time budgets. A route can forbid replay after
dispatch; a failure there comes back to you instead of being retried. Streaming
retries happen while the response is still held. Once the stream has started,
the HTTP status is already sent and a later failure arrives as an error event
in the stream.
A retry keeps the model you asked for and tries another eligible route. With
an explicit X-GM-Model-Cascade the retry advances through the sequence you
declared. X-GM-Providers limits retries of a single-model request to the
listed providers; it is rejected on a multi-model cascade. See routing.
When every matching route is rate-limited, you get HTTP 429 with
Retry-After. When the retry budget runs out before a response begins, you get
HTTP 503 with Retry-After, or the saved context-window error described
below. These 503
errors use error.code: "upstream_unavailable" on OpenAI-compatible routes,
error.type: "overloaded_error" on Anthropic Messages, and
error.status: "UNAVAILABLE" on Gemini.
Upstream 4xx responses
Section titled “Upstream 4xx responses”Upstream 400, 413, and 422 request errors normally return in the called
surface’s error envelope. The gateway can retry a recognized route-surface
mismatch or provider-account failure. It can also retry a recognized
context-window mismatch when capability retries are enabled. If those context
retries are exhausted, the buyer receives the saved 400, 413, or 422
request error, so the next step is to adjust the request.
Upstream 4xx responses other than 400, 413, 422, and 429 are
provider-side failures and are eligible for another attempt under the same
retry limits. A 404 for a pinned previous_response_id ends that request.
Provider-side failures that reach the buyer use the gateway’s availability
envelope.
The available field in /v1/models is advisory. A model can change state
after discovery, so callers must still handle a routing failure.