Respuestas y errores
Cada respuesta es JSON con el mismo sobre. El éxito o el fallo está en el campo status, no en el estado HTTP: comprueba status y luego lee el resultado.
Las respuestas exitosas devuelven la misma metadata superior. Los datos especificos viven en organic, images, news, videos, places o place.
statusnumberrequerido
Codigo de estado de negocio. 0 significa exito.
request_idstringrequerido
ID estable para soporte, reintentos y correlacion de logs.
elapsed_msnumberrequerido
Duracion observada por gateway en milisegundos.
credits_chargednumber | nullrequerido
Creditos cobrados despues de aplicar reembolsos.
search_typestringopcional
Tipo de respuesta del producto, si se devuelve.
errorstringrequerido
Mensaje de error legible.
Solicitud completada. Revisa los campos del producto; no_results no prueba HTTP 404.
Cobrado
Cuerpo o parámetros ausentes o inválidos.
Sin cobroCorrige la solicitud antes
Clave ausente, inválida o revocada.
Sin cobroCorrige la solicitud antes
Recurso no encontrado en rutas o catálogo del gateway.
Sin cobroCorrige la solicitud antes
Saldo insuficiente.
Sin cobroCorrige la solicitud antes
Límite QPS o de concurrencia excedido.
Sin cobroSe puede reintentar
Error interno inesperado.
Sin cobroSe puede reintentar
El worker devolvió error de obtención o análisis del origen.
Sin cobroSe puede reintentar
No hay sesión de worker disponible.
Sin cobroSe puede reintentar
El gateway agotó el tiempo esperando al worker.
Sin cobroSe puede reintentar
{
"status": 1001,
"error": "unauthorized",
"request_id": "0f3576b2-6e2e-4f1e-bb0e-8cb0d4a60195",
"elapsed_ms": 0,
"credits_charged": 0
}Cada respuesta incluye estas cabeceras para que tu cliente regule el ritmo y decida si reintentar sin analizar el mensaje.
- X-RateLimit-Limit
- Solicitudes por segundo que permite tu cuenta.
- X-RateLimit-Remaining
- Solicitudes que aún caben en el segundo actual.
- Retry-After
- Si se rechaza, segundos a esperar antes de reenviar.
- X-SerpBase-Retryable
- true si reenviar la misma solicitud puede funcionar; false si hay que cambiarla.
Tiempos de espera
Configura el tiempo de espera de tu cliente HTTP en 60 segundos; los ejemplos de código de esta documentación ya lo hacen. Cada solicitud termina de nuestro lado en 30 segundos como máximo, con un resultado o un error, así que 60 segundos dejan margen para la red.
- La mayoría de las solicitudes responden en pocos segundos, pero algunas tardan 15–20 segundos: cuando Google va lento o pide verificación, reintentamos por otras rutas dentro de esos 30 segundos. Un tiempo de espera más corto corta justo las solicitudes que estaban a punto de tener éxito.
- Si tu cliente se rinde antes, detenemos la solicitud y la reembolsamos, pero no recibes ni resultado ni un error con el que actuar. No pongas el tiempo de espera de tu cliente por debajo de 30 segundos.
- Si necesitas responder más rápido, indícalo con el parámetro timeout (1–30 segundos) en los endpoints de búsqueda de Google: los reintentos empiezan antes para ajustarse a tu presupuesto y, cuando se agota, recibes status 1504 al instante, sin cobro. Mantén el tiempo de espera de tu cliente HTTP por encima.
- Si aun así una solicitud falla o se agota el tiempo, vuelve a enviarla; solo se cobra el intento que tiene éxito.