Códigos de Erro

Referência de códigos de erro HTTP e formato de respostas de erro da API de Integrações.

Formato de erro

Todas as respostas de erro seguem o mesmo formato JSON:

{
    "status_code": 400,
    "message": "Descrição do erro",
    "error": "Bad Request"
}

Códigos HTTP

Código	Significado	Quando ocorre
`200`	OK	Requisição bem-sucedida (GET, PATCH)
`201`	Created	Recurso criado com sucesso (POST)
`204`	No Content	Recurso removido com sucesso (DELETE)
`400`	Bad Request	Dados inválidos, filtro desconhecido, versão inválida
`401`	Unauthorized	Token ausente, inválido ou expirado
`403`	Forbidden	Sem permissão para a operação
`404`	Not Found	Recurso não encontrado
`409`	Conflict	Conflito (ex: recurso duplicado)
`422`	Unprocessable Entity	Payload bem formado, mas semanticamente inválido
`429`	Too Many Requests	Rate limit excedido
`500`	Internal Server Error	Erro interno do servidor

Troubleshooting

401 Unauthorized

Causa: Token de autenticação ausente, inválido ou expirado.

Soluções:

Verifique se o header Authorization está presente
Confirme que o formato é Bearer sk_<id>_<secret> ou Bearer bit_<token>
Verifique se a API Key não foi revogada
Verifique se a API Key não expirou (expires_at)

403 Forbidden

Causa: O token é válido, mas não tem permissão para a operação.

Soluções:

Verifique as permissões da API Key (recurso + ação)
Para OAuth: confirme que o usuário tem a role necessária
Recursos admin_only requerem role admin

400 Bad Request

Causa: Dados enviados são inválidos.

Cenários comuns:

Campo obrigatório ausente no body
Tipo de dado incorreto (ex: string onde esperava number)
Filtro com campo não suportado pelo recurso
Header api-version com versão inválida
Formato de UUID inválido

422 Unprocessable Entity

Causa: o corpo da requisição está bem formado e passou na validação de tipos, mas a API não conseguiu processar o conteúdo.

Cenários comuns:

Geografia não resolvida: country_code, state/state_id ou city/city_id que a API não conseguiu casar com o catálogo interno com segurança. Não há degradação silenciosa — se você enviou o campo, ele precisa resolver. Ver Clientes e Dados de referência.
Snapshot financeiro incompatível em notas de compra, quando o total muda sem o payables correspondente.

O corpo do erro traz details.fields — um mapa de campo → lista de motivos — apontando exatamente o que falhou. As mensagens de details vêm em inglês:

{
    "status_code": 422,
    "message": "Could not resolve provided geography fields",
    "error": "Unprocessable Entity",
    "details": {
        "fields": {
            "country_code": [
                "Could not resolve country from '1112' (tried ISO2, ISO3, numeric code and names)"
            ],
            "city": ["Could not resolve city from 'CidadeQueNaoExiste' in country 'BR'"]
        }
    }
}

Solução: consulte o catálogo em Dados de referência e envie os IDs (state_id, city_id) em vez do texto livre quando precisar de determinismo.

429 Too Many Requests

Causa: Rate limit excedido.

Endpoints com rate limit:

GET /oauth/authorize: 20 req/min por IP
POST /oauth/token: 10 req/min por client_id

Solução: Implemente backoff exponencial e respeite os headers de retry.

404 Not Found

Causa: Recurso não existe ou pertence a outro tenant.

Nota: Por segurança, a API retorna 404 (não 403) quando o recurso existe mas pertence a outro tenant.

Health check

O endpoint GET /health responde 200 OK quando a API está no ar — use-o para monitoramento. Ele não exige autenticação nem contexto de tenant.

Códigos de Erro

Nesta página