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

# Erros

> Formato padronizado de erro (RFC 7807) e códigos comuns.

Toda resposta de erro da API da Cativa segue o **mesmo formato**, baseado no padrão [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807). Esta página descreve esse formato e os códigos HTTP que você pode encontrar.

## Formato padrão de erro

```json theme={null}
{
  "type": "Validation.Email.Invalid",
  "status": 400,
  "title": "Validation Error",
  "detail": "The request failed validation.",
  "traceId": "0HMV5JK6L6NPL:00000003"
}
```

| Campo     | Tipo   | Descrição                                                                                              |
| --------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `type`    | string | Identificador estável do tipo de erro. Use para branchear a lógica do seu lado.                        |
| `status`  | número | Código HTTP repetido no body (compatibilidade RFC 7807).                                               |
| `title`   | string | Categoria curta do erro (`Validation Error`, `Not Found`, `Forbidden`, `Internal Server Error`, etc.). |
| `detail`  | string | Mensagem em inglês descrevendo o problema. **Não exiba diretamente para o usuário final.**             |
| `traceId` | string | Correlaçã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

| Status            | Title                                  | O que significa                                                                              | O que fazer                                                       |
| ----------------- | -------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `400`             | `Validation Error` ou `Business Error` | Body 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.          |
| `403`             | `Forbidden`                            | Token válido, mas sem permissão para a operação.                                             | Confira escopo da API Key ou OAuth.                               |
| `404`             | `Not Found`                            | Recurso não existe.                                                                          | Confirmar `id`.                                                   |
| `422`             | `Unprocessable Entity`                 | Body válido em formato, mas entidade inválida (regras de domínio).                           | Ler `detail` e ajustar.                                           |
| `500`             | `Internal Server Error`                | Erro 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`

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

## Antipattern: ignorar `traceId` nos logs

<Warning>
  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.
</Warning>

## Como reportar um erro

Ao abrir um ticket em [dev@cativa.digital](mailto: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

<CardGroup cols={2}>
  <Card title="Identidade e usuários" icon="user" href="/pt-BR/concepts/identity-and-users">
    Onde você verá `400 Validation Error` (campo inválido) com mais frequência.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/pt-BR/concepts/webhooks">
    Como o `X-Cativa-Execution-Id` ajuda a deduplicar webhooks reentregues.
  </Card>
</CardGroup>