Gateway Error Codes
Distinguish request, permission, quota, and upstream failures.
Errors use a consistent envelope with success=false and an error object containing code and message. An upstream credential failure is never misreported as the user's API key failure.
Do not blindly retry every 4xx. Retry only when the error and request idempotency allow it; UPSTREAM_OUTCOME_UNKNOWN needs special handling because the upstream may have executed the request. For streaming, never restart automatically after output has been emitted.
Key points
- 400/422: invalid request or field validation.
- 401: invalid API key or authentication state.
- 403: subscription, scope, model, or restriction denied access.
- 409: durable state conflict.
- 429: rate limit exceeded.
- 502/503: provider, upstream credential, or dependency failure.
- SSE can emit an error data event or disconnect before [DONE]; clients must preserve partial output and surface a terminal error.