API Reference

Error codes

Gateway-generated errors use this response shape:

{
  "error": {
    "message": "invalid api key",
    "code": "invalid_api_key"
  }
}

Use the HTTP status and error.code for program logic. Treat error.message as diagnostic text because some messages include request-specific details. The gateway does not add an error.type field to errors it generates.

When the request reaches the gateway, the response also includes X-Request-Id. Keep it for Call Logs and support requests.

Request and policy errors

HTTP error.code Meaning What to do
400 invalid_body The gateway could not read the request body Send a readable request body and valid Content-Length or transfer encoding
400 model_not_allowed The API key does not allow the requested model Select an allowed model or update the key's model scope
400 max_output_tokens_exceeded The requested output-token budget exceeds the key policy Lower max_tokens or max_output_tokens, or update the key policy
401 missing_platform_authorization The request has no API key Send Authorization: Bearer $APIGO_API_KEY
401 invalid_api_key The API key was not found or cannot be resolved Check the Bearer token and confirm the key is enabled in API Keys
402 quota_exceeded The API key is marked as having exhausted its quota Review the key status and quota configuration before retrying
402 insufficient_balance The Workspace has no positive available funds Add funds or increase configured credit, then wait for the admission snapshot to refresh
402 day_limit_reached The API key reached its daily spend cap Wait for the next day in the Workspace time zone or raise the cap
402 d7_limit_reached The API key reached its trailing 7-day spend cap Wait for spend to leave the window or raise the cap
402 d30_limit_reached The API key reached its trailing 30-day spend cap Wait for spend to leave the window or raise the cap
403 apikey_inactive The API key is not active Enable the key or use another active key
405 method_not_allowed /v1/models was called with a method other than GET Use GET /v1/models
429 hydrate_cooldown API-key state refresh is temporarily cooling down Retry with backoff
429 api_key_rpm_exceeded This API key exhausted its RPM capacity Respect Retry-After and reduce this key's request rate
429 api_key_tpm_exceeded This API key exhausted its TPM capacity Respect Retry-After and reduce this key's token rate
429 api_key_concurrency_exceeded This API key exhausted its concurrency capacity Wait for this key's in-flight requests to finish
429 workspace_rpm_exceeded The Workspace exhausted its shared RPM capacity Respect Retry-After and reduce aggregate Workspace traffic
429 workspace_tpm_exceeded The Workspace exhausted its shared TPM capacity Respect Retry-After and reduce aggregate Workspace token rate
429 workspace_concurrency_exceeded The Workspace exhausted its shared concurrency capacity Wait for in-flight Workspace requests to finish

Gateway service errors

These errors usually require platform or provider investigation. Retry transient failures with bounded exponential backoff. Contact support with X-Request-Id if they continue.

HTTP error.code Meaning
500 identifier_generation_failed The gateway could not generate a request ID
500 resolver_not_configured The API-key resolver is unavailable
500 local_quota_not_configured The local quota coordinator is unavailable
502 auth_resolve_failed The gateway could not resolve API-key state
502 rate_limit_config_invalid The resolved rate-limit configuration is invalid
502 missing_upstream_base_url The resolved provider endpoint is missing
502 invalid_upstream_base_url The resolved provider endpoint is invalid
502 upstream_request_failed The gateway could not complete the provider request

Upstream passthrough errors

Provider responses pass through with their original HTTP status and response body. Their error.type, error.code, and error.message depend on the provider and may be absent.

Codes such as rate_limited and upstream_unavailable are not generated by the current gateway. Handle them only when the upstream response actually contains them.

See Limits and request enforcement for the relationship between balance, spend caps, and the two runtime-limit layers.

Debug order

  1. Classify the failure by HTTP status and error.code.
  2. Keep X-Request-Id.
  3. Find the request in Call Logs.
  4. Fix the API key, model policy, spend cap, or request parameters for request errors.
  5. Retry transient upstream or service errors with bounded backoff.
Previous
Rate limits