Responses API Beta Error Handling | Basic Error Guide | OpenRouter

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:

Code	Description	Equivalent HTTP Status
`invalid_prompt`	Request or prompt validation failed (context length exceeded, invalid request fields)	400
`rate_limit_exceeded`	Too many requests	429
`image_content_policy_violation`	Input or output flagged by a content filter	400
`server_error`	Internal server error, authentication failure, provider overloaded/unavailable, or timeout	500+

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.