Entenda como a API Checktudo comunica erros e como tratá-los adequadamente em sua aplicação.
Códigos de Status HTTP
Sucesso (2xx)
| Código | Status | Descrição |
|---|
| 200 | OK | Requisição bem-sucedida |
| 201 | Created | Recurso criado com sucesso |
| 204 | No Content | Requisição bem-sucedida sem conteúdo de retorno |
Erros do Cliente (4xx)
| Código | Status | Descrição |
|---|
| 400 | Bad Request | Parâmetros inválidos na requisição |
| 401 | Unauthorized | API Key inválida ou ausente |
| 402 | Payment Required | Saldo insuficiente |
| 403 | Forbidden | Sem permissão para o recurso |
| 404 | Not Found | Recurso não encontrado |
| 409 | Conflict | Conflito com estado atual do recurso |
| 422 | Unprocessable Entity | Dados válidos mas não processáveis |
| 429 | Too Many Requests | Rate limit excedido |
Erros do Servidor (5xx)
| Código | Status | Descrição |
|---|
| 500 | Internal Server Error | Erro interno do servidor |
| 502 | Bad Gateway | Erro de comunicação com serviços externos |
| 503 | Service Unavailable | Serviço temporariamente indisponível |
| 504 | Gateway Timeout | Timeout na comunicação externa |
Códigos de Erro por Categoria
Autenticação
| Código | Descrição | Solução |
|---|
INVALID_API_KEY | API Key inválida | Verifique se a chave está correta |
EXPIRED_API_KEY | API Key expirada | Solicite renovação |
MISSING_API_KEY | API Key não fornecida | Inclua o header x-api-key |
INSUFFICIENT_PERMISSIONS | Permissões insuficientes | Verifique permissões da chave |
Validação
| Código | Descrição | Solução |
|---|
INVALID_LICENSE_PLATE | Placa em formato inválido | Use formato ABC1234 ou ABC1D23 |
INVALID_CPF | CPF inválido | Verifique os 11 dígitos |
INVALID_CHASSIS | Chassi inválido | Verifique os 17 caracteres |
MISSING_REQUIRED_KEY | Chave obrigatória ausente | Inclua todas as chaves requeridas |
INVALID_UF | UF inválida | Use sigla de 2 caracteres |
Consultas
| Código | Descrição | Solução |
|---|
VEHICLE_NOT_FOUND | Veículo não encontrado | Verifique placa/chassi/renavam |
PERSON_NOT_FOUND | Pessoa não encontrada | Verifique o CPF |
QUERY_NOT_FOUND | Consulta não encontrada | Verifique o queryId |
TEMPLATE_NOT_FOUND | Template não encontrado | Verifique o slug do template |
QUERY_PROCESSING | Consulta ainda em processamento | Aguarde e tente novamente |
QUERY_FAILED | Falha na consulta | Tente reprocessar |
Pagamento/Saldo
| Código | Descrição | Solução |
|---|
INSUFFICIENT_BALANCE | Saldo insuficiente | Adicione créditos à conta |
PAYMENT_REQUIRED | Pagamento necessário | Regularize pendências |
Rate Limiting
| Código | Descrição | Solução |
|---|
RATE_LIMIT_EXCEEDED | Limite de requisições excedido | Aguarde o reset ou upgrade do plano |
Disponibilidade
| Código | Descrição | Solução |
|---|
SOURCE_UNAVAILABLE | Fonte de dados indisponível | Tente novamente em alguns minutos |
DETRAN_UNAVAILABLE | DETRAN indisponível | Aguarde e tente novamente |
SERVICE_MAINTENANCE | Serviço em manutenção | Aguarde término da manutenção |
Troubleshooting
Erro 401 - API Key Inválida
- Verifique se a chave foi copiada corretamente
- Confirme que está usando o header correto (
x-api-key)
- Verifique se a chave não expirou no painel
Erro 403 - Permissão Negada
- Verifique as permissões da sua API Key
- Confirme que o recurso está liberado para seu plano
Erro 429 - Rate Limit
- Implemente cache local
- Reduza a frequência de requisições
- Considere upgrade de plano
Erro 503 - Serviço Indisponível
- Aguarde alguns minutos
- Verifique o status da API
Próximos Passos