Skip to content

Errors

Every error has the same shape, with a stable code to branch on:

{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "...",
"param": "input",
"request_id": "req_9f2c4e..."
}
}
  • type groups codes into five families, so you can handle a whole class of errors at once.
  • code is the contract. Existing codes never change meaning. New codes can be added: handle a code you don’t know by its type or HTTP status.
  • message explains the error for a person. Its wording can change, so never match on it.
  • param names the field at fault for a validation_error, as a dotted path. Otherwise it is null.
  • request_id identifies the request. Every response, success or error, also carries it in the X-Request-ID header. Quote it when you contact support.

Retry-After (in seconds) comes with a 429 or 503 when waiting will help.

Long research-tool calls can deliver an error in a 200 body. See Long-running requests.

type code Status When
invalid_request_error validation_error 422 The request failed validation; param names the field
bad_request 400 A malformed request, for example an unknown company or an outdated cursor
not_found 404 The resource does not exist, or you cannot see it
conflict 409 The request conflicts with the current state
tool_failed 422 A research tool cannot answer the call as asked, for example a company with no structured financial data. message is the tool’s explanation. Repeating the call unchanged will not help
method_not_allowed 405 The wrong HTTP method for the endpoint
authentication_error unauthenticated 401 No credentials were sent
invalid_api_key 401 The key is unknown, revoked or expired
permission_error permission_denied 403 Authenticated, but not allowed
api_key_not_allowed 403 An API key on a path outside the public API
upgrade_required 403 Your plan does not include this. required_entitlements lists what would unlock it
rate_limit_error insufficient_credits 429 A credit cap is reached. See Credits
rate_limited 429 Too many requests in a minute. See Rate limits
api_error request_timeout 408 The request ran past its time budget
db_pool_exhausted 503 The service is busy. Retry after Retry-After
user_not_provisioned 503 Your account is still being set up. Retry after Retry-After
auth_unavailable 503 Your key could not be verified just now. Retry after Retry-After
service_unavailable 503 A temporary outage
upstream_unavailable 502, 504 A service Marvin depends on failed or timed out
internal_error 500 An unexpected error on our side. Quote the request_id to support

A resource you may not read answers 404, not 403, so the API never reveals whether someone else’s conversation or report exists.

  • Retry with backoff: 429 rate_limited, every 503, 502 and 504, and 500 internal_error. Wait for Retry-After when it is present, otherwise back off exponentially.
  • Retry after the window resets: 429 insufficient_credits, which carries Retry-After when a reset is coming.
  • Don’t retry unchanged: every 4xx other than 429. Fix the request first.

POST /v1/responses starts a new turn each time it is called. If a call fails with an unclear outcome (a dropped connection, a timeout on your side), check the conversation with GET /v1/conversations/{id}/items before you retry, or you may ask the question twice.