Error Handling

Responses API Beta

Understanding and handling errors in the Responses API.

This API is in beta stage and may have breaking changes.
It is also stateless: each request is independent and no conversation state is persisted between requests.

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

Error Response Format

All errors follow this structure:

responses-error-handling-01.json


{
  "error": {
    "code": "invalid_prompt",
    "message": "Detailed error description"
  },
  "metadata": null
}

Error Codes

The API uses the following error codes:

Code	Description	Equivalent HTTP Status
`invalid_prompt`	Request validation failed	400
`rate_limit_exceeded`	Too many requests	429
`server_error`	Internal server error	500+