Errores
Un solo formato de error, con códigos estables sobre los que programar.
Los errores usan el formato problem details del RFC 9457, con
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." }]
}Usa code en tu código: es estable. title, detail y message son para personas y pueden cambiar. Cada
respuesta, buena o mala, trae un encabezado X-Request-Id: inclúyelo cuando escribas a soporte.
Códigos
| Estado | code | Qué hacer |
|---|---|---|
| 400 | invalid_json, invalid_request | Corrige el pedido. errors lista cada campo inválido. Los campos desconocidos también se rechazan. |
| 400 | invalid_url, invalid_site, site_not_found, unsupported | Corrige la URL o el sitio. |
| 401 | missing_api_key, invalid_api_key, revoked_api_key | Mira Autenticación. |
| 402 | budget_too_small | Sube max_tokens. |
| 403 | robots_disallowed | El robots.txt del sitio no lo permite o no se pudo leer (lo reintentamos a los 10 minutos). |
| 404 | job_not_found | El trabajo no existe para esta key, o venció (duran un día). |
| 429 | rate_limited | Reintenta después de Retry-After segundos. |
| 429 | quota_exceeded | Se usó la cuota diaria de tokens. Se renueva a las 00:00 UTC. |
| 502 | site_unreachable, invalid_redirect, bot_protection | Falló el sitio. Prueba más tarde u otro sitio. |
| 503 | upstream_unavailable, browser_unavailable | Temporal. Reintenta con espera creciente. |
| 504 | timeout, site_timeout | Temporal. Reintenta, o usa un modo más liviano. |
Reintentos
Los SDKs reintentan dos veces los errores de conexión, 429 rate_limited y 5xx, con espera exponencial y
aleatoria, respetando Retry-After. Nunca reintentan quota_exceeded. Si llamas a la API directamente,
haz lo mismo.
Los avisos no son errores
Lo que no detiene un pedido —un dominio que no está en el índice, un tope alcanzado— vuelve en el arreglo
warnings de la respuesta, cada uno con un code y un message.