Erros

Toda falha tem a mesma estrutura e um code estável. Tome decisões com base no código: a mensagem é escrita para pessoas e pode mudar.

{ "error": { "code": "invalid_key", "message": "That API key does not exist." } }

Alguns erros trazem campos extras além desses dois: parameter para indicar o parâmetro errado, retry_after para dizer quanto esperar, limit e used para uma cota esgotada.

Todos os códigos

Status	Código	Quando
400	`missing_query`	`query` veio vazio ou ausente.
400	`unknown_format`	`format` não é um dos seis.
400	`unknown_column`	`columns` cita um campo que não existe.
400	`format_not_available`	Foi pedido um formato plano onde a resposta não é composta de linhas.
400	`per_page_too_large`	`per_page` acima do limite de linhas do seu plano. O limite vem no erro.
400	`invalid_json`	O corpo do POST não é um JSON válido.
401	`missing_key`	Não há cabeçalho `Authorization: Bearer`.
401	`invalid_key`	A chave não corresponde a nenhuma conta.
403	`plan_required`	A conta não tem plano pago.
404	`unknown_endpoint`	Esse caminho não existe. Os conhecidos vêm listados no erro.
405	`method_not_allowed`	A API é somente leitura. Use GET, ou POST com um corpo JSON.
429	`too_many_requests`	Requisições chegando a mais de dez por minuto (API e MCP somados).
429	`quota_exceeded`	A cota de buscas do dia acabou.
429	`snippet_quota_exceeded`	A cota de trechos do dia acabou. Buscas sem trechos continuam funcionando.

O que fazer em cada caso

400: a sua requisição está errada, e repeti-la não vai ajudar. O campo parameter indica qual parâmetro.
401, 403: problema na sua chave ou no seu plano. Não vale a pena tentar de novo até que algo mude.
429 too_many_requests: espere retry_after segundos e repita. Nada foi consumido.
429 quota_exceeded: a cota volta à meia-noite UTC seguinte; retry_after diz quanto falta. Tentar antes não vai ajudar.
5xx: problema nosso. Tente de novo com intervalos cada vez maiores.

Erros e formatos

Os erros voltam em JSON, ou em XML quando foi pedido format=xml. Os formatos planos não têm estrutura para um erro, então uma requisição que falhou e tinha pedido csv recebe JSON. Por isso, um cliente que lê CSV deve verificar o código de status em vez de supor que todo corpo de resposta sejam linhas.

Como ler os códigos sem ler esta página

GET / lista todos os códigos acima, com o significado de cada um, em JSON. Não exige chave, então é possível construir um cliente que trate o conjunto completo sem que ninguém precise abrir um navegador.

curl https://api.publicwww.com/

A seguir Exemplos de código