Error Codes and Error Handling

All /v1/* interfaces in Inference Space return errors as structured JSON so clients can parse and handle them by branch instead of receiving a bare connection reset without an error body.

Private deployments use the same error structure and error codes → Enterprise Private Deployment.

Error Response Structure

OpenAI-compatible APIs, including /v1/chat/completions and /v1/images/*:

{
  "error": {
    "message": "Human-readable error description",
    "type": "invalid_request_error",
    "code": "optional_machine_code"
  }
}

The Anthropic-native /v1/messages API adds a top-level type: 'error':

{
  "error": {
    "message": "Human-readable error description",
    "type": "invalid_request_error"
  },
  "type": "error"
}

• message: Human-readable description that can be shown directly to developers. We do not recommend displaying it directly to end users.
• type: Error type. Rate limits use rate_limit_exceeded; parameter and routing errors use invalid_request_error; authentication errors are listed below.
• code: Some errors include a stable machine code, such as a pricing-missing safeguard or uncaught-exception fallback, for precise branching.

Authentication Errors

Authentication is checked consistently before a request enters the business route. API keys must be sent as Authorization: Bearer gk_... (including the Bearer scheme prefix; a bare gk_... is rejected).

Data-plane authentication errors use a flat structure: the top-level error is the error code and message is its description. This differs from the nested { error: { type, message } } structure used by business errors below:

{
  "error": "missing_api_key",
  "message": "API key required (Authorization: Bearer gk_...)"
}

The three conversational APIs (/v1/chat/completions, /v1/messages, and /v1/responses) require the ai:chat scope on the data plane. A missing scope returns 403 insufficient_scope. See Authentication and API Keys for details.

Routing Errors

LLM APIs require a target provider. Specify it with ?provider=X, body.provider, or the X-Provider header. The Anthropic-native /v1/messages API defaults to the anthropic provider.

{
  "error": {
    "message": "'provider' is required: pass it via ?provider=X or body.provider (valid: anthropic, dashscope, deepseek, ...)",
    "type": "invalid_request_error"
  }
}

Rate-Limit Errors (429)

Exceeding a rate or quota limit returns 429, with type set to rate_limit_exceeded. The retry-after response header provides the recommended number of seconds to wait.

{
  "error": {
    "message": "rate limit exceeded",
    "type": "rate_limit_exceeded"
  }
}

HTTP/1.1 429 Too Many Requests
retry-after: 12
content-type: application/json

See Rate Limits and Quotas for rate-limit dimensions and backoff recommendations.

Missing-Pricing Safeguard (402)

When a model lacks valid pricing information for the current organization, the gateway actively rejects the request instead of billing it at zero. It returns 402, sets type to billing_error, and includes the stable machine code MISSING_MULTI_CURRENCY_PRICE. This means the model pricing has not been confirmed. Contact support or an administrator to complete the organization's pricing, then retry.

{
  "error": {
    "message": "Model pricing has not been confirmed. Please contact support.",
    "type": "billing_error",
    "code": "MISSING_MULTI_CURRENCY_PRICE"
  }
}

Uncaught-Exception Fallback (503)

Any internal exception not caught by business logic is converted by the gateway into a 503 with a JSON body (machine code handler_unhandled_exception) instead of a connection reset or protocol interruption. Clients can always parse an error body.

{
  "error": {
    "code": "handler_unhandled_exception",
    "message": "internal handler error: <detail>",
    "type": "Error"
  }
}

A 503 handler_unhandled_exception indicates a transient gateway-side failure, so you may retry a limited number of times.

Retry Recommendations

• 429: Back off for the duration in the retry-after header before retrying. Do not retry repeatedly without backoff. See Rate Limits and Quotas.
• Transient 5xx errors, such as 503 or network instability: Retry a limited number of times (we recommend ≤ 3 attempts with exponential backoff) to avoid extending the overall timeout.
• 400 / 401 / 403 / 402: These are request-side problems involving parameters, authentication, authorization, or pricing. Retrying is ineffective; correct the issue and send the request again.