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

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.

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

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.

The available field in /v1/models is advisory. A model can change state after discovery, so callers must still handle a routing failure.