AI API Error Responses

LLMPool returns protocol-native error formats for its OpenAI-compatible and Anthropic-compatible APIs. Applications should check the HTTP status first, then read the structured fields for the selected protocol.

Error messages are written for people and are not a stable parsing contract. Do not branch or retry by matching message text.

OpenAI-compatible format

Normalized OpenAI-compatible errors return an error object:

{
  "error": {
    "message": "The requested model was not found.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

Use the HTTP status and error.code as the primary signals. Use error.type for broad categories such as authentication, invalid requests, rate limits, and server failures.

Anthropic-compatible format

Normalized Anthropic-compatible errors return a top-level type: "error" envelope:

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested model was not found."
  }
}

Anthropic clients should primarily use the HTTP status and error.type.

Who defines each field

In short: the common structured codes and types documented here are the LLMPool client contract. A message is never a stable contract and can change without changing the meaning of an error.

Non-2xx business response exception

Some compatible relays incorrectly attach a non-2xx status to a structurally valid business response. After validating that the response matches the target endpoint, LLMPool can preserve that HTTP status and return the business object instead of replacing it with a normalized error envelope:

• Chat Completions and Responses can return a valid OpenAI business object.
• Non-streaming Anthropic Messages, Files, and Message Batches can return a valid Anthropic business object.
• A Responses object can have status: "failed" while retaining the normal Response object shape and usage information.

This exception does not apply to an unrecognized body or a failed streaming handshake; those continue through normalized error handling. Raw HTTP clients receiving a non-2xx response should first check whether the body is a valid object for the target endpoint before reading an error envelope. SDK behavior for non-2xx business objects can vary.

Common HTTP statuses

See Troubleshooting for causes and detailed actions.

Streaming errors

A stream can fail after HTTP 200 and the response headers have already been sent. Clients must continue parsing SSE events instead of checking only the initial HTTP status.

Chat Completions

Chat Completions sends an OpenAI error object in the SSE data field:

{
  "error": {
    "message": "Upstream stream interrupted.",
    "type": "server_error",
    "param": null,
    "code": "stream_error"
  }
}

Responses API

The Responses API sends a top-level error event with the next sequence_number:

{
  "type": "error",
  "code": "stream_error",
  "message": "Upstream stream interrupted.",
  "param": null,
  "sequence_number": 7
}

The Responses API can also produce a valid response.failed terminal event:

{
  "type": "response.failed",
  "sequence_number": 7,
  "response": {
    "id": "resp_123",
    "object": "response",
    "status": "failed",
    "error": {
      "code": "server_error",
      "message": "The response failed."
    }
  }
}

response.failed is a Responses protocol terminal state, not a synthetic LLMPool stream_error. LLMPool forwards it, ends the stream, and does not append another synthetic error. Clients must handle both type: "error" and type: "response.failed".

Anthropic Messages

Anthropic Messages uses an SSE event: error event:

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "Upstream stream interrupted."
  }
}

End the current stream after receiving a streaming error or failed terminal state. Do not treat previously received content as a complete response. Whether to submit a new request depends on whether the operation can be retried safely.

Retry guidance

• 400, 401, 402, 403, 404, 405, 413, and 422 generally require a request or account change and should not be retried unchanged.
• 429 rate_limit_exceeded, 429 rate_limited, 502 upstream_unavailable, 503 service_unavailable, 504 upstream_timeout, and 529 overloaded_error can be retried with exponential backoff and jitter.
• 502 upstream_configuration_error and 400/500 meter_price_rules_error indicate platform configuration problems; retrying unchanged will usually not help.
• Retry 500 internal_error or Anthropic 500 api_error only a limited number of times, then stop and contact support. Anthropic api_error can also represent upstream configuration failure, so its type alone does not identify the root cause.
• Honor the Retry-After header when present.
• Before retrying non-idempotent operations such as resource or Batch creation, determine whether the first request may have succeeded.
• Set both a maximum attempt count and an overall retry deadline to prevent retry storms.

LLMPool does not include raw upstream responses, upstream credentials, internal model names, API bases, or proxy addresses in normalized errors. Do not send complete API keys, request bodies, or file contents when contacting support.

See Troubleshooting for Files, Batches, Responses, and other specialized operations.