API GuidesResponses API

Error Handling

Understanding and handling errors in the Responses API Beta
Beta API

This API is in beta stage and may have breaking changes. Use with caution in production environments.

Stateless Only

This API is stateless - each request is independent and no conversation state is persisted between requests. You must include the full conversation history in each request.

The Responses API Beta returns structured error responses that follow a consistent format.

Error Response Format

All errors follow this structure:

1{
2  "error": {
3    "code": "invalid_prompt",
4    "message": "Detailed error description"
5  },
6  "metadata": null
7}

Error Codes

The API uses the following error codes:

CodeDescriptionEquivalent HTTP Status
invalid_promptRequest or prompt validation failed (context length exceeded, invalid request fields)400
rate_limit_exceededToo many requests429
image_content_policy_violationInput or output flagged by a content filter400
server_errorInternal server error, authentication failure, provider overloaded/unavailable, or timeout500+

These codes are a reduced mapping of the internal typed error codes. Multiple internal error types collapse into each Responses API code — for example, context_length_exceeded and invalid_request both surface as invalid_prompt here.

Canonical error_type Field

Because the native error.code vocabulary is lossy (many distinct errors collapse to server_error), failed responses also include a top-level error_type field that carries the precise canonical error type:

1{
2  "id": "resp_abc123",
3  "status": "failed",
4  "error": { "code": "server_error", "message": "Invalid credentials" },
5  "error_type": "authentication"
6}

The error_type value matches one of the typed error codes and is stable across all OpenRouter API formats. Use it to programmatically distinguish error categories when the native code is ambiguous.