Códigos de Erro

Formato de erro

Todas as respostas de erro seguem o mesmo formato JSON:

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

Códigos HTTP

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

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.