Erros
A API Pública usa códigos HTTP padrão para indicar sucesso ou falha. Todas as respostas de erro seguem o mesmo formato JSON.
{
"detail": "Mensagem descritiva do erro"
}
{
"detail": [
{
"loc": ["body", "nome"],
"msg": "Campo obrigatório",
"type": "value_error.missing"
}
]
}
Tabela de códigos
| Código | Status | Descrição | Quando ocorre |
|---|
200 | OK | Requisição bem-sucedida | Operação executada com sucesso |
201 | Created | Recurso criado | POST que cria novo recurso |
400 | Bad Request | Requisição malformada | JSON inválido, parâmetros incorretos |
401 | Unauthorized | Não autenticado | API Key ausente, inválida ou revogada |
403 | Forbidden | Sem permissão | Plano sem api_access habilitado |
404 | Not Found | Recurso não encontrado | ID inexistente ou recurso de outra empresa |
422 | Unprocessable Entity | Erro de validação | Campos obrigatórios ausentes ou formato inválido |
429 | Too Many Requests | Rate limit excedido | Mais de 60 req/min por API Key |
500 | Internal Server Error | Erro interno | Erro inesperado no servidor |
Exemplos por código
401 — API Key inválida
{
"detail": "API Key inválida ou não fornecida"
}
403 — Plano sem acesso
{
"detail": "Seu plano não inclui acesso à API Pública. Faça upgrade para continuar."
}
404 — Recurso não encontrado
{
"detail": "Cliente não encontrado"
}
422 — Erro de validação
{
"detail": [
{
"loc": ["body", "nome"],
"msg": "Campo obrigatório",
"type": "value_error.missing"
}
]
}
429 — Rate limit excedido
{
"detail": "Rate limit excedido. Tente novamente em alguns segundos."
}
500 — Erro interno
{
"detail": "Erro interno do servidor. Tente novamente mais tarde."
}
Boas práticas de tratamento
Sempre verifique o código HTTP antes de processar a resposta. Implemente retry apenas para erros 429 e 5xx.
- 401/403: verifique se a API Key está correta e se o plano possui
api_access
- 404: confirme que o ID existe e pertence à sua empresa
- 422: valide os dados antes de enviar; confira campos obrigatórios e formatos
- 429: implemente backoff exponencial; respeite o header
Retry-After
- 500: tente novamente após alguns segundos; se persistir, entre em contato com o suporte
