Formato da response de erro
Todos os erros retornam um body JSON com o seguinte formato:| Campo | Tipo | Descrição |
|---|---|---|
statusCode | integer | O código de status HTTP |
message | string | Uma mensagem de erro legível ou um código de erro programático (ex: auth.invalid_credentials) |
errors | array | Detalhes de validação. Presente em responses 400 com erros por campo. |
resourceId | string | O ID do recurso não encontrado. Presente em algumas responses 404. |
O campo
message também funciona como código de erro para tratamento programático. Códigos programáticos seguem o padrão {domínio}.{erro} — por exemplo, auth.invalid_credentials, organization.not_found, subscription.active_subscription_exists.Códigos de status HTTP
| Status | Nome | Quando ocorre |
|---|---|---|
400 | Bad Request | Falha de validação, campos obrigatórios ausentes ou input malformado |
401 | Unauthorized | Access token ausente, expirado ou inválido |
403 | Forbidden | Permissões insuficientes ou ação adicional necessária (veja sub-códigos 403) |
404 | Not Found | O recurso solicitado não existe |
409 | Conflict | Recurso duplicado ou conflito de estado (ex: assinatura já existe) |
422 | Unprocessable Entity | Violação de regra de negócio (ex: plano não elegível para downgrade) |
429 | Too Many Requests | Limite de requisição excedido (veja Limites de Requisição) |
500 | Internal Server Error | Erro inesperado no servidor |
Padrões de tratamento de erros
Sub-códigos 403
O status403 é usado tanto para erros de permissão quanto para sinais de controle de fluxo. Quando você receber um 403, inspecione o campo message para determinar a ação necessária:
| Código | Significado | Ação necessária |
|---|---|---|
auth.organization_selection_required | Usuário pertence a múltiplas organizações | Chame Trocar Organização com o organizationId desejado |
auth.otp_verification_required | Email ainda não verificado | Complete a verificação de OTP |
auth.method_not_allowed | Conta usa um método de autenticação diferente | Use o fluxo de autenticação correto (ex: OAuth em vez de senha) |
auth.invitation_required | Usuário precisa ser convidado antes de acessar a plataforma | Solicite um convite a um administrador da organização |
forbidden | Permissões RBAC insuficientes | Verifique se o usuário tem a permissão resource:action necessária |
Erros de validação (400)
Erros de validação incluem um arrayerrors com detalhes por campo:
errors contém:
| Campo | Descrição |
|---|---|
message | A regra de validação que falhou (ex: required, invalid_format, too_long) |
path | O campo que falhou na validação |
Estratégias de recuperação de erros
Identificar a categoria do erro
Verifique o código de status HTTP primeiro, depois inspecione o campo
message para códigos de erro específicos.Tratar erros que podem ser retentados
401 (token expirado): renove o token e retente.
429 (rate limited): aguarde o período do
Retry-After e retente.
500 (erro no servidor): retente com backoff exponencial (veja abaixo).Tratar erros que não devem ser retentados
400 (validação): corrija o body da request e reenvie.
403 (proibido): verifique permissões ou siga as instruções do sub-código.
404 (não encontrado): verifique se o ID do recurso existe.
409 (conflito): resolva o estado de conflito antes de retentar.
Implementar backoff exponencial para retentativas
Para erros que podem ser retentados, aumente o intervalo entre tentativas para evitar sobrecarregar o servidor.
Idempotência
Algumas operações são seguras para retentar, enquanto outras não:| Seguro para retentar | Não seguro para retentar |
|---|---|
Todas as requests GET | POST para criar recursos (pode criar duplicatas) |
Atualizações PUT / PATCH | POST /invoices/{id}/pay (pode cobrar duas vezes) |
Requests DELETE (idempotentes por natureza) |
Cenários de erro comuns
| Cenário | Status | Código | Solução |
|---|---|---|---|
Header Authorization ausente | 401 | unauthorized | Inclua Bearer {token} no header |
| Token expirado | 401 | unauthorized | Renove o token e retente |
| Usuário sem permissão | 403 | forbidden | Atribua a role/permissão necessária |
| Organização não encontrada | 404 | organization.not_found | Verifique o organizationId |
| Assinatura já existe | 409 | subscription.active_subscription_exists | Verifique a assinatura existente antes de criar |
| Cupom expirado | 409 | coupon.not_available | Use um código de cupom válido |
| Máximo de métodos de pagamento atingido | 409 | payment_method.max_of_3_card_payment_methods_reached | Exclua um método de pagamento existente primeiro |
Próximos passos
Limites de Requisição
Entenda os limites de requisição e implemente estratégias de backoff.
Autenticação
Aprenda sobre gerenciamento de tokens e fluxos de renovação.