Códigos de erro

A API segue convenções HTTP padrão. Esta página lista os status codes que você pode encontrar e como tratá-los.

Status codes

Status	Significado	Quando acontece
200 OK	Sucesso	Requisição processada e respondida com sucesso
400 Bad Request	Body / query inválidos	Campo obrigatório ausente, tipo de dado incorreto, formato fora do esperado
401 Unauthorized	Falha de autenticação	Credencial ausente, inválida, expirada, ou assinatura HMAC incorreta
403 Forbidden	Falta de permissão	Credencial válida, mas sem acesso ao app CRM ou à permissão ADMIN
404 Not Found	Recurso não encontrado	event key desconhecida, ou rota inexistente
500 Internal Server Error	Erro interno	Falha inesperada no servidor — pode tentar novamente

Formato do corpo de erro

Erros seguem o formato padrão do NestJS:

{
  "statusCode": 401,
  "message": "Unauthorized",
  "error": "Unauthorized"
}

Para erros de validação (400), o campo message é um array com os problemas encontrados:

{
  "statusCode": 400,
  "message": [
    "anonymousId should not be empty",
    "key must be a valid enum value"
  ],
  "error": "Bad Request"
}

Como tratar

Erro	Ação recomendada
400	Corrigir o payload antes de retentar. Não retente em loop — o erro é determinístico.
401	Verificar credencial. Para JWT, renovar o token. Para API Key, recalcular a assinatura.
403	Verificar permissões da chave/usuário no painel CRM.
404 (event key)	Conferir a lista de eventos suportados.
500	Implementar retry com backoff exponencial (máx. 3 tentativas). Se persistir, contatar suporte.

Idempotência

Os endpoints de ingestão (/track, /customer-events, /identify) não são idempotentes — duas chamadas idênticas registram dois eventos. Se você precisar de idempotência, use o campo dispatchId para correlacionar e deduplicar no seu lado.