Skip to content
SayGMDocs
Dashboard

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.

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.

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.

Filtering the catalog with an unrecognized value returns HTTP 200 and an empty list rather than a 400:

Terminal window
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.

For retryable failures:

  1. Honor Retry-After when present.
  2. Use exponential backoff with jitter.
  3. Cap both attempts and total elapsed time.
  4. Avoid automatic retries after a streaming response has emitted content.
  5. Log a request identifier and status, never the API key or sensitive prompt.

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 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.