Erros
Códigos de erro e como tratá-los.
Formato de Erro
Todos os erros retornam um JSON com o campo error:
JSON
{ "error": "Mensagem descritiva do erro." }Códigos HTTP
| Código | Significado | Quando ocorre |
|---|---|---|
| 200 | OK | Requisição bem-sucedida |
| 201 | Created | Recurso criado (ex: nova API Key) |
| 400 | Bad Request | Parâmetro obrigatório ausente ou inválido |
| 401 | Unauthorized | Chave inválida, inativa ou e-mail não corresponde |
| 404 | Not Found | Empresa ou recurso não encontrado |
| 429 | Too Many Requests | Limite de chaves ativas atingido |
| 500 | Internal Server Error | Erro interno — tente novamente em instantes |
Erros Comuns
Credenciais inválidas (401)
JSON
{ "error": "Chave inválida ou inativa." }
{ "error": "E-mail não corresponde à chave informada." }Solução: Verifique se o e-mail é o mesmo usado ao criar a chave, e se a chave não foi desativada.
Header ausente (401)
JSON
{ "error": "Headers X-API-Key e X-Declara-Email são obrigatórios." }Solução: Adicione ambos os headers em todas as requisições autenticadas.
Limite de chaves (429)
JSON
{ "error": "Limite de 5 chaves ativas atingido. Desative uma antes de criar outra." }Solução: Acesse Integrações → HS Financeiro no Declara e desative uma chave que não está mais em uso.
Erro interno (500)
JSON
{ "error": "Erro ao consultar notas: ..." }Solução: Tente novamente. Se persistir, entre em contato com o suporte.