Pular para o conteúdo principal
Toda resposta de erro da API da Cativa segue o mesmo formato, baseado no padrão RFC 7807 Problem Details. Esta página descreve esse formato e os códigos HTTP que você pode encontrar.

​
Formato padrão de erro

{
  "type": "Validation.Email.Invalid",
  "status": 400,
  "title": "Validation Error",
  "detail": "The request failed validation.",
  "traceId": "0HMV5JK6L6NPL:00000003"
}
CampoTipoDescrição
typestringIdentificador estável do tipo de erro. Use para branchear a lógica do seu lado.
statusnúmeroCódigo HTTP repetido no body (compatibilidade RFC 7807).
titlestringCategoria curta do erro (Validation Error, Not Found, Forbidden, Internal Server Error, etc.).
detailstringMensagem em inglês descrevendo o problema. Não exiba diretamente para o usuário final.
traceIdstringCorrelação para debug. Inclua em qualquer ticket de suporte.
Em respostas de validação, um campo adicional errors pode ser populado com erros por campo, no formato Dictionary<string, ProblemDetailsFieldError[]>.

​
Códigos HTTP comuns

StatusTitleO que significaO que fazer
400Validation Error ou Business ErrorBody inválido em formato (JSON malformado, content-type errado) ou regra de negócio violada.Conferir o request antes de retentar.
401—Token ausente, inválido ou expirado.Renovar/gerar nova credencial. Não retente sem ação.
403ForbiddenToken válido, mas sem permissão para a operação.Confira escopo da API Key ou OAuth.
404Not FoundRecurso não existe.Confirmar id.
422Unprocessable EntityBody válido em formato, mas entidade inválida (regras de domínio).Ler detail e ajustar.
500Internal Server ErrorErro do lado da Cativa.Retentar com backoff. Se persistir, abrir ticket com o traceId.
502/503/504—Indisponibilidade transitória.Retentar com backoff exponencial.

​
Exemplo de 400 Validation Error

{
  "type": "Validation.User.Email.Required",
  "status": 400,
  "title": "Validation Error",
  "detail": "Email is required.",
  "traceId": "0HMV5JK6L6NPL:00000003"
}

​
Antipattern: ignorar traceId nos logs

Sempre logue traceId junto com qualquer erro da API que você capture. Sem ele, o time de suporte da Cativa não consegue investigar seu caso — é como pedir ajuda sem dizer que erro deu. Inclua traceId, código HTTP e type no seu logger desde o primeiro dia.

​
Como reportar um erro

Ao abrir um ticket em dev@cativa.digital, inclua sempre:
  1. O traceId retornado no corpo da resposta de erro.
  2. O type e o status do erro.
  3. Um exemplo do request (URL, método, headers relevantes — sem expor a chave por inteiro).
  4. Horário aproximado (com fuso) em que o erro aconteceu.
Esses dados permitem ao time correlacionar com os logs internos rapidamente.

​
Próximos passos

Identidade e usuários

Onde você verá 400 Validation Error (campo inválido) com mais frequência.

Webhooks

Como o X-Cativa-Execution-Id ajuda a deduplicar webhooks reentregues.