Errors
One error format everywhere, with stable codes you can program against.
Errors use RFC 9457 problem details, with
Content-Type: application/problem+json:
{
"type": "urn:typesearch:error:invalid_request",
"title": "Pedido inválido",
"status": 400,
"detail": "query: La consulta necesita dos letras como mínimo.",
"code": "invalid_request",
"request_id": "req_8fKq2mZr1xYt",
"errors": [{ "path": "query", "message": "La consulta necesita dos letras como mínimo." }]
}Use code in your code — it is stable. title, detail and message are for people, can change, and
are currently written in Spanish. Every response, successful or not, carries an X-Request-Id header:
include it when you contact support.
Codes
| Status | code | What to do |
|---|---|---|
| 400 | invalid_json, invalid_request | Fix the request. errors lists each invalid field. Unknown fields are rejected too. |
| 400 | invalid_url, invalid_site, site_not_found, unsupported | Fix the URL or site. |
| 401 | missing_api_key, invalid_api_key, revoked_api_key | See Authentication. |
| 402 | budget_too_small | Raise max_tokens. |
| 403 | robots_disallowed | The site’s robots.txt disallows it, or it couldn’t be read (we retry after 10 minutes). |
| 404 | job_not_found | The job does not exist for this key, or it expired (jobs last a day). |
| 429 | rate_limited | Retry after Retry-After seconds. |
| 429 | quota_exceeded | Daily token quota used. It resets at 00:00 UTC. |
| 502 | site_unreachable, invalid_redirect, bot_protection | The site failed. Try again later or another site. |
| 503 | upstream_unavailable, browser_unavailable | Temporary. Retry with backoff. |
| 504 | timeout, site_timeout | Temporary. Retry, or use a lighter mode. |
Retries
The SDKs retry connection errors, 429 rate_limited and 5xx twice, with exponential backoff and
jitter, honouring Retry-After. They never retry quota_exceeded. Calling the API directly, do the same.
Warnings are not errors
Things that don’t stop a request — a domain that is not in the index, a budget reached — come back in
the response’s warnings array, each with a code and a message.