Model APIs
Errors, 429 responses and retry policy
Distinguish credential, validation, model, rate-limit and upstream errors, with bounded retries and request ids.
Updated
Diagnose by HTTP status
| Status | Meaning and action |
|---|---|
| 400 | Invalid JSON, messages or model parameters; correct the request |
| 401 | Missing, invalid or wrong credential type; verify the API key |
| 402 | Billing or budget refusal; check wallet and limits |
| 403 | Scope, group or access policy denial; check the current key |
| 404 | Unavailable endpoint, model or resource; verify path and id |
| 413 | Payload too large; reduce file, image or context size |
| 429 | Gateway or provider rate limiting; inspect error and Retry-After |
| 500 / 502 / 503 / 504 | Service, upstream or timeout failure; record request id and retry within bounds |
Keep the body and request id
Gateway errors use {"error":{"type":"ferrogate_error","code":"...","message":"...","request_id":"..."}}. Provider names, URLs, native codes and messages are never returned. Keep code, HTTP status, x-request-id and Retry-After when present; branch on code.
{"error":{"code":"invalid_request","message":"Request validation failed"}}Where a 429 originates
A 429 means the request was rate limited. gateway_capacity_exceeded and gateway_provider_rate_limited distinguish the source; honor Retry-After or retry-after-ms for either.
Use Retry-After or retry-after-ms when supplied and correlate the error code with usage history. Reduce concurrency, bound output and stagger loops. For persistent failures, report time, model, task id and request id.
Complete error code reference
These are the stable public gateway codes. Any provider_*, upstream_* or native provider error is converted to a gateway_* code; internal diagnostics stay in server evidence.
| Code | HTTP | Scenario and action |
|---|---|---|
| gateway_provider_circuit_open | 503 | Circuit open; retry later |
| gateway_provider_unavailable | 502/503 | Unavailable; bounded retry |
| gateway_provider_timeout | 504 | Timeout; backoff and retry |
| gateway_provider_unreachable | 502 | Connection or transport failure; bounded retry |
| gateway_provider_authentication_failed | 502 | Provider credential failure; contact admin |
| gateway_provider_rate_limited | 429 | Provider rate limit; honor Retry-After |
| gateway_provider_request_rejected | 502 | Provider refusal; correct parameters |
| gateway_provider_invalid_response | 502 | Invalid response; report request_id |
| gateway_provider_protocol_error | 502 | Protocol mismatch; contact admin |
| gateway_provider_response_too_large | 502 | Response too large; reduce output |
| gateway_provider_stream_interrupted | 502 或流中 200 | Stream incomplete; mark incomplete before retry |
| gateway_provider_configuration_error | 502 | Gateway configuration missing; contact admin |
| gateway_capacity_exceeded | 429 | Gateway capacity; reduce concurrency |
| gateway_timeout | 504 | Gateway timeout; backoff and retry |
| gateway_request_rejected | 400 | Gateway validation; correct request |
| gateway_internal_error | 500 | Unexpected failure; report request_id |
Billing behavior for every error
The gateway charges only tokens it observes and writes to the usage ledger. “Gateway charge” means the Token4AI wallet; a provider may charge after a disconnect, which the gateway cannot guarantee. Observed partial output is charged.
| Category | Gateway charge | Rule |
|---|---|---|
| Request validation/auth/model/policy/quota | 否 | No provider call before refusal |
| gateway_capacity_exceeded, gateway_timeout before dispatch | 否 | No provider call |
| gateway_provider_circuit_open | 否 | Circuit short-circuits before dispatch |
| Provider auth/rate-limit/refusal/invalid/protocol/oversize | 否（无 usage） | No settled tokens from error response |
| Unreachable or timeout | 否（无 usage） | Partial stream: charge observed tokens |
| gateway_provider_stream_interrupted | 按已观测 token | Zero without usage; charge observed usage/output |
| Successful 2xx | 按实际 usage | Provider usage or permitted local estimate |
Bounded retries
- Retry only recoverable rate-limit, timeout or transient service failures; 400/401/403 usually require configuration changes.
- Respect server retry hints, use exponential backoff with jitter, and set both an attempt limit and an overall deadline.
- Choose one layer, such as the SDK or task runner, to own retries rather than multiplying them across layers.
- After partial output or a write tool call, retries can duplicate side effects and incur additional usage.