Tratamento de Erros

Formato de resposta de erro e códigos de erro comuns.

Formato de Erro

Todo erro inclui uma mensagem error e um code:

Resposta de erro

{
  "error": "Mensagem curta legível por humanos",
  "code": "ERROR_CODE"
}

Erros de validação incluem detalhes adicionais:

Erro de validação

{
  "error": "Validação falhou",
  "code": "VALIDATION_ERROR",
  "errors": [
    { "path": "/body/name", "message": "deve ser string" }
  ]
}

Códigos de Erro Comuns

Status	Código	Descrição
`400`	`VALIDATION_ERROR`	Corpo da requisição ou parâmetros inválidos.
`401`	`UNAUTHORIZED`	Chave de API ausente ou inválida.
`402`	`INSUFFICIENT_BALANCE`	Créditos insuficientes para a operação.
`402`	`PAYMENT_FAILED`	Pagamento de ativação da empresa falhou.
`403`	`FORBIDDEN`	Empresa não está ativa.
`404`	`NOT_FOUND`	Recurso não existe.
`409`	`ALREADY_PROCESSED`	Ativação já processada.
`409`	`CONVERSATION_CLOSED`	Conversa não está mais ativa.
`500`	`INTERNAL_ERROR`	Erro inesperado do servidor.

Tratando Erros 402

Se receber INSUFFICIENT_BALANCE, o plano da empresa não cobre a ação e não há créditos pré-pagos suficientes. Compre créditos via POST /api/companies/credits/purchase e tente novamente.

Boas Práticas

Sempre verifique o campo code, não o status HTTP, para tratamento programático de erros.
Registre a resposta de erro completa para depuração.
Apresente a mensagem error aos usuários quando apropriado.
Implemente lógica de retry com backoff exponencial para erros 500.

← Anterior Autenticação Próximo → SDK JavaScript