Errors

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"
  }
}

Common Gateway codes include invalid_json, bad_model_id, model_not_found, model_disabled, provider_disabled, provider_not_supported, invalid_tokenizer, credit_balance_exhausted, 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.

Exhausted credits (402)

When the organization's credit balance is confirmed to be zero and no eligible provider has usable BYOK credentials, the Gateway returns 402 Payment Required with billing_error:

{
  "error": {
    "type": "billing_error",
    "code": "credit_balance_exhausted",
    "message": "No Edgee credits remaining. Add credits or configure BYOK for this model."
  }
}

{
  "type": "error",
  "error": {
    "type": "billing_error",
    "message": "No Edgee credits remaining. Add credits or configure BYOK for this model."
  }
}

Add credits in Settings → Credits, or configure BYOK for a provider eligible to serve the model. If you cannot change these settings, ask an organization administrator. Repeated retries will not resolve this error until credits or credentials change. A BYOK key for an unrelated provider will not help.

This check happens before inference starts, so it returns a JSON error even when stream: true was requested. Usage limits and routing-strategy budget blocks still return 429.

Unavailable usage (503)

If usage data cannot be read or is incomplete, the Gateway cannot verify the credit balance. It temporarily blocks Edgee-funded routes with 503; eligible BYOK routes remain usable. Retry with backoff rather than purchasing credits to resolve this error.

Chat Completions and Responses use code: "usage_unavailable"; Messages uses the Anthropic envelope with error.type: "api_error". The message for an unavailable balance is Usage data temporarily unavailable. Please try again.

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.