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..." }}typegroups codes into five families, so you can handle a whole class of errors at once.codeis the contract. Existing codes never change meaning. New codes can be added: handle a code you don’t know by itstypeor HTTP status.messageexplains the error for a person. Its wording can change, so never match on it.paramnames the field at fault for avalidation_error, as a dotted path. Otherwise it isnull.request_ididentifies the request. Every response, success or error, also carries it in theX-Request-IDheader. 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.
Retrying
Section titled “Retrying”- Retry with backoff:
429 rate_limited, every503,502and504, and500 internal_error. Wait forRetry-Afterwhen it is present, otherwise back off exponentially. - Retry after the window resets:
429 insufficient_credits, which carriesRetry-Afterwhen a reset is coming. - Don’t retry unchanged: every
4xxother than429. 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.