Erros de API e limites de taxa

Os erros retornam { "error": { "code": "…", "message": "…", "details": … } } com um status HTTP correspondente.

• 400 invalid_parameter: um parâmetro de consulta como desde, até ou resultado está malformado.
• 401 não autorizado: chave ausente, inválida ou revogada.
• 403 plan_required: o acesso à API precisa de um plano Scale ou superior em pelo menos um site.
• 403 insuficiente_scope: a chave é somente leitura.
• 429 cooldown, simultaneidade, daily_quota, mensal_quota, concorrente_quota ou host_busy: aplica-se um limite de auditoria de SEO; veja retry_at e Retry-After.
• 403 org_suspended: entre em contato com o suporte.
• 404 not_found: o recurso não existe na sua organização.
• Conflito 409: o termo de pesquisa já existe para esse país e dispositivo.
• 422 validação_failed / limit_exceeded / plan_required / project_unverified: veja mensagem e detalhes.
• 429 rate_limited: aguarde alguns segundos para tentar novamente.
• 500 erro_interno: tente novamente; entre em contato com o suporte se persistir.
• 503 indisponível: a API está temporariamente indisponível; tente novamente com espera.

Limites de taxa

120 solicitações por minuto por chave. Uma resposta 429 inclui Retry-After: 60. Cada solicitação é registrada na chave, e o horário da última utilização da chave (atualizado no máximo uma vez por minuto) é mostrado em Configurações → Chaves de API.

Limites do plano

Adicionar ou alterar termos nunca reduz silenciosamente seus números: se uma solicitação ultrapassar o limite de termos de pesquisa ou de cliques por dia do site, ela falhará com 422 e informará quanto resta.