Documentação / Guias

Tratamento de erros

Identifique os códigos e saiba como reagir.

Use o status HTTP para identificar o resultado geral e o campo code, quando presente, para decidir como sua aplicação deve agir.

JSON · exemplo

{
  "status": "Erro",
  "code": 1003,
  "message": "O número de requisições por minuto excedeu o limite do plano."
}

Código	Significado	O que fazer
`1000`	Registro não encontrado	Confira o identificador e trate a ausência de dado.
`1001`	Token não informado	Envie Authorization no cabeçalho.
`1002`	Token inválido	Verifique a chave e a configuração da integração.
`1003`	Limite por minuto excedido	Diminua a frequência e aguarde antes de tentar novamente.
`1004`	Créditos esgotados	Consulte o saldo e ajuste o plano ou os créditos.
`1005`	Tempo real não permitido	Verifique as permissões do workspace.
`1006`	Saldo insuficiente para tempo real	Confira o saldo necessário para a busca externa.
`1007`	CEP inválido	Confira o formato e os dígitos do CEP.
`1008`	Parâmetros geoespaciais ausentes	Informe latitude, longitude e raioMetro.
`1009`	Latitude inválida	Use um valor entre -90 e 90.
`1010`	Longitude inválida	Use um valor entre -180 e 180.
`1011`	Raio inválido	Informe um raio maior que zero, na unidade exigida pelo endpoint.
`1012`	Recurso restrito a planos pagos	Confira o plano necessário para a operação.
`1013`	Filtros incompatíveis	Não combine q com logradouro.
`1014`	Falha do provedor externo	Tente novamente após uma espera, com limite de tentativas.
`9999`	Erro não mapeado	Leia a mensagem e registre o contexto sem incluir seu token.

Status HTTP

Os endpoints podem responder com estes status:

400: parâmetros ou permissões inválidos.
401: token inválido.
404: registro ausente.
405: falta de créditos.
429: excesso de requisições.
500: falha interna.
502: falha de provedor externo.

As respostas documentadas por operação estão na referência. Falhas de autenticação e de limite podem ocorrer antes da execução do endpoint, mesmo quando não aparecem na lista de respostas do OpenAPI.

Retentativas

Não repita automaticamente erros de token, parâmetros ou falta de saldo.
Para erros transitórios, use espera progressiva e limite de tentativas. Se houver Retry-After, respeite-o.
Uma resposta de erro pode não ter corpo JSON. Verifique o tipo de conteúdo e trate respostas vazias.
Após um timeout, o servidor pode já ter processado a consulta. Repetir a operação pode gerar novo consumo de créditos.

Se precisar de ajuda, envie à equipe o endpoint, o horário e o código do erro. Não envie seu token.