Respostas e erros
Cada resposta é JSON com o mesmo envelope. Sucesso ou falha está no campo status, não no status HTTP: verifique status e depois leia o resultado.
Respostas bem-sucedidas retornam a mesma metadata superior. Os dados especificos ficam em organic, images, news, videos, places ou place.
statusnumberobrigatorio
Codigo de status de negocio. 0 significa sucesso.
request_idstringobrigatorio
ID estavel para suporte, retentativas e correlacao de logs.
elapsed_msnumberobrigatorio
Duracao observada pelo gateway em milissegundos.
credits_chargednumber | nullobrigatorio
Creditos cobrados apos aplicar reembolsos.
search_typestringopcional
Tipo de resposta do produto, quando retornado.
errorstringobrigatorio
Mensagem de erro legivel.
Solicitação concluída. Verifique campos do produto; no_results não prova HTTP 404.
Cobrado
Corpo ou parâmetros ausentes ou inválidos.
Sem cobrançaCorrija a solicitação antes
Chave ausente, inválida ou revogada.
Sem cobrançaCorrija a solicitação antes
Recurso não encontrado nas rotas ou catálogo do gateway.
Sem cobrançaCorrija a solicitação antes
Saldo insuficiente.
Sem cobrançaCorrija a solicitação antes
Limite QPS ou de concorrência excedido.
Sem cobrançaPode repetir
Erro interno inesperado.
Sem cobrançaPode repetir
O worker retornou erro de obtenção ou análise da origem.
Sem cobrançaPode repetir
Não há sessão de worker disponível.
Sem cobrançaPode repetir
O gateway excedeu o tempo esperando pelo worker.
Sem cobrançaPode repetir
{
"status": 1001,
"error": "unauthorized",
"request_id": "0f3576b2-6e2e-4f1e-bb0e-8cb0d4a60195",
"elapsed_ms": 0,
"credits_charged": 0
}Cada resposta traz estes cabeçalhos para que seu cliente controle o ritmo e decida se repete sem analisar a mensagem.
- X-RateLimit-Limit
- Solicitações por segundo permitidas na sua conta.
- X-RateLimit-Remaining
- Solicitações ainda permitidas no segundo atual.
- Retry-After
- Se recusada, segundos a esperar antes de reenviar.
- X-SerpBase-Retryable
- true se reenviar a mesma solicitação pode funcionar; false se ela precisa mudar.
Tempos limite
Configure o tempo limite do seu cliente HTTP para 60 segundos; os exemplos de código desta documentação já fazem isso. Cada solicitação termina do nosso lado em no máximo 30 segundos, com um resultado ou um erro, então 60 segundos deixam folga para a rede.
- A maioria das solicitações responde em poucos segundos, mas algumas levam 15–20 segundos: quando o Google está lento ou pede verificação, tentamos de novo por outras rotas dentro desses 30 segundos. Um tempo limite menor corta justamente as solicitações que estavam prestes a dar certo.
- Se o seu cliente desistir antes, interrompemos a solicitação e reembolsamos, mas você não recebe resultado nem um erro para tratar. Não use um tempo limite do cliente abaixo de 30 segundos.
- Se precisar responder mais rápido, diga isso com o parâmetro timeout (1–30 segundos) nos endpoints de busca do Google: as novas tentativas começam antes para caber no seu orçamento e, quando ele acaba, você recebe status 1504 na hora, sem cobrança. Mantenha o tempo limite do seu cliente HTTP acima dele.
- Se mesmo assim uma solicitação falhar ou o tempo esgotar, envie de novo; só a tentativa com sucesso é cobrada.