AI Gateway Errors

Both planes return a structured errors array. The inference plane additionally wraps it in the envelope the calling SDK expects, so OpenAI and Anthropic SDK exceptions work unchanged while the Telnyx detail remains available.

Error envelopes

{
  "errors": [
    {
      "code": "precondition_failed",
      "title": "Stale If-Match",
      "detail": "The resource version has changed; read it again.",
      "meta": { "current_version": 4 }
    }
  ]
}

{
  "error": {
    "message": "Send either max_tokens or max_completion_tokens, not both.",
    "type": "invalid_request_error",
    "param": "max_completion_tokens",
    "code": "invalid_request"
  },
  "errors": [
    {
      "code": "invalid_request",
      "title": "Invalid request",
      "detail": "Send either max_tokens or max_completion_tokens, not both.",
      "meta": {}
    }
  ]
}

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Model is not available to this token key."
  },
  "request_id": "0b1c2d3e-4f50-4617-8a29-3b4c5d6e7f80",
  "errors": [
    {
      "code": "model_not_in_catalog",
      "title": "Model not allowed",
      "detail": "Model is not available to this token key.",
      "meta": { "scope": "token_key" }
    }
  ]
}

Every response carries an X-Request-ID header. Keep it, together with the code, when reporting a problem. Do not log authorization headers, token keys or full request objects. An error that occurs after a streaming response has started cannot change the HTTP status. On the OpenAI surface it arrives as an error chunk; on the Anthropic surface, as an event: error frame. Consume every stream to completion and handle the SDK’s stream exceptions.

Status codes

Status	Meaning	Action
`400`	Invalid body, unsupported option or model-specific option, unknown field, request over the size limits, token key limit out of range, invalid date or page parameter.	Correct the request.
`401`	Missing or wrong credential for this plane.	Use a Telnyx API key on the management plane and an `ltg_sk_` token key on the inference plane.
`403`	Blocked, revoked or expired key; blocked resource; model not allowed; budget or end-user policy denied.	Read the `code`. Do not treat `403` as retryable.
`404`	Resource does not exist or belongs to another account.	Check the ID.
`405`	Method not allowed, for example `PATCH` on a provider key.	Provider keys cannot be edited; create a new one instead.
`409`	Idempotency conflict, membership conflict or pagination snapshot conflict.	Read the `code`.
`412`	Stale `If-Match`.	Read the resource and retry with the current ETag.
`428`	Missing `If-Match` (or `If-None-Match: *` on end-user create).	Add the precondition header.
`429`	Rate limit exceeded.	Wait for `Retry-After`. Remember that inference retries are not idempotent.
`502`	The model provider failed.	Fail closed. The request may or may not have consumed provider work.
`503`	Enforcement, catalog, policy propagation or a required dependency is unavailable, or a BYOK model has no attached provider key for its provider.	Fail closed. Do not switch credentials or bypass the gateway.

Error codes

Code	Status	Meaning
`invalid_request`	400	Malformed or unsupported request, including a request over the size limits and a request to `/v1/messages` with a model that is not an Anthropic BYOK model (use `/v1/chat/completions` for those).
`limit_out_of_range`	400	A token key `max_budget`, `rpm_limit` or `tpm_limit` is 0 or above its maximum. See Token key limits.
`invalid_token_key`	401	The inference credential is missing, malformed or unknown.
`unauthorized`	401 / 403	The credential is not valid for this plane or resource.
`token_key_blocked`	403	The key is blocked, revoked or expired.
`resource_blocked`	403	The key’s user, group or asserted end user is blocked.
`budget_exceeded`	403	A key, user or group budget lacks headroom for the request’s reservation.
`end_user_budget_exceeded`	403	The asserted end user’s budget lacks headroom.
`model_not_in_catalog`	403	The model is not in the key’s or group’s allowlist.
`rate_limit_exceeded`	429	An RPM or TPM limit was hit.
`not_found`	404	No such resource in this account.
`conflict`	409	Membership or pagination snapshot conflict.
`idempotency_conflict`	409	The `Idempotency-Key` was reused with a different body, or the original request is still in progress.
`precondition_failed`	412	`If-Match` does not match the current version.
`precondition_required`	428	A required precondition header is missing.
`enforcement_unavailable`	503	Policy, catalog or a dependency needed to admit the request is unavailable, or the request uses a BYOK model and the key’s group has no attached provider key for that model’s provider.
`upstream_error`	502	The model provider returned an error.

Handling guidance

Never resolve an error by escalating credentials. A Telnyx API key, provider secret or any other credential is rejected on the inference plane by design.
Retry management mutations with the same idempotency key. A new key on retry can create a duplicate resource.
Do not automatically retry inference. A timeout or 502 is not proof that no provider work happened. Retry only errors that occurred before dispatch, and honor Retry-After on 429.
Re-read before re-writing. On 412, fetch the resource, review the change that landed, and apply your update to the current version.
Fail closed on 503. The old policy may no longer apply; wait and retry rather than assuming the request is authorized. For a BYOK model, check that the group has a provider key attached for that model’s provider.

AI Gateway

API

Concepts

For AI Agents

AI Gateway Errors

Error envelopes

Status codes

Error codes

Handling guidance

​Error envelopes

​Status codes

​Error codes

​Handling guidance

Error envelopes

Status codes

Error codes

Handling guidance