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. Así se ve uno pedido con Accept-Language: es:
{
"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.
title y detail vienen en inglés; envía Accept-Language: es para recibirlos en español. 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. |
| 402 | insufficient_credits | No queda crédito en tu cuenta. Recarga en el panel. |
| 402 | spend_limit_reached | La key llegó a su tope de gasto del mes. Súbelo en el panel. |
| 403 | robots_disallowed | El robots.txt del sitio no lo permite o no se pudo leer (lo reintentamos a los 10 minutos). |
| 403 | source_unavailable | La fuente no está disponible ahora. No decimos por qué, y puede ser temporal. Prueba con otra fuente. |
| 404 | job_not_found | El trabajo no existe para esta key, o venció (duran un día). |
| 404 | chart_not_found | No hay un gráfico con ese id para tu organización: se borró o venció. Mira Gráficos. |
| 422 | insufficient_data | Un gráfico desde una consulta no encontró notas sobre el tema en el período (con index o questions: no hay datos suficientes para el gráfico). No se cobra. Prueba con más days o una consulta más amplia. |
| 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. |
| 499 | cancelled | La búsqueda se detuvo porque el cliente cerró la conexión o cortó el flujo. No hay nada que corregir; vuelve a enviarla si todavía la necesitas. |
| 500 | internal_error | Algo falló de nuestro lado. Reintenta; si se repite, escribe a soporte con el request_id. |
| 502 | site_unreachable, invalid_redirect, bot_protection | Falló el sitio. Prueba más tarde u otro sitio. |
| 503 | upstream_unavailable, browser_unavailable, browser_busy | Temporal. Reintenta con espera creciente; browser_busy dice cuándo en Retry-After. |
| 503 | shutting_down | El servidor se está reiniciando. Reintenta después de Retry-After segundos. |
| 503 | spend_cap_reached | El servicio llegó a su tope de gasto del día. Retry-After dice cuándo se renueva (00:00 UTC). |
| 503 | job_interrupted | En el error de un trabajo (GET /v1/jobs/{id}): el servidor se reinició antes de terminarlo. Vuelve a pedirlo. |
| 504 | timeout, site_timeout | Temporal. Reintenta, o usa un modo más liviano. |
En POST /v1/contents cada URL tiene su propio estado: una página de una fuente que
no está disponible vuelve con source_unavailable en results[].error.code, y el resto del pedido sale bien.
Reintentos
Los SDKs reintentan dos veces los errores de conexión, los tiempos de espera agotados, 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 (en inglés, o en español con
Accept-Language: es).