Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.cativa.digital/llms.txt

Use this file to discover all available pages before exploring further.

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"
}

​
Idempotência em chamadas de escrita

Suporte nativo ao header Idempotency-Key será publicado em breve. Por enquanto, evite duplicatas no seu lado: dedupe pelos campos lógicos (ex: email para criação de usuário) e trate 409 (recurso já existe) como sucesso lógico.

​
Rate limits

Limites de taxa por API Key ou IP serão publicados em breve. Por enquanto, projete clients tolerantes a falhas transitórias com backoff exponencial em respostas 5xx.

​
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.

​
Próximos passos

Identidade e usuários

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

Webhooks

Idempotência também se aplica do lado de quem recebe webhooks.