Errors
Understand Gateway HTTP errors and streaming failures
Check both the HTTP status and response body. Gateway errors normally use an OpenAI-shaped envelope:
{
"error": {
"type": "invalid_request_error",
"code": "bad_model_id",
"message": "Invalid model ID: 'invalid-model'"
}
}
message and type are present in Gateway-generated errors. code and param are optional. Native upstream errors can preserve provider-specific fields.
Messages endpoints also use Anthropic-shaped errors. Authentication failures while resolving the Edgee key can still use the common Gateway envelope, so accept either shape:
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "Missing 'model' field in request body"
}
}
| HTTP status | Meaning |
|---|---|
400 | Malformed request, unknown or disabled model/provider, or request semantics that cannot be converted to the destination format. |
401 | Missing or invalid credentials. |
403 | Inactive/expired key, model restriction or another permission failure. |
404 | Unknown endpoint, or an upstream resource that does not exist. |
413 | Request too large, when returned by the request path. |
429 | Provider rate limit, usage limit, or routing-strategy budget exhausted. Check the message before retrying. |
500 | Internal processing or provider failure mapped to an internal error. |
502 | Upstream provider failure on paths using the common Gateway error mapping. |
503 | Usage accounting or an upstream service is temporarily unavailable. |
529 | Provider overloaded, when preserved by the request path. |
Common Gateway codes include invalid_json, bad_model_id, model_not_found, model_disabled, provider_disabled, provider_not_supported, invalid_tokenizer, usage_limit_exceeded, usage_unavailable, provider_error and internal_error. These are examples, not an exhaustive list. The same failure can use a different envelope depending on whether the request was forwarded natively or converted.
Streaming errors
Once SSE headers have been sent, an error cannot change the HTTP status. Inspect stream error events even when the initial status is 200. Chat Completions streams use the [DONE] terminator; Responses streams use typed completion/failure events and do not use [DONE].
Messages streaming works with supported non-Anthropic destinations through format conversion; it is not restricted to the Anthropic provider. Provider-native features are not guaranteed across formats.