> ## Documentation Index
> Fetch the complete documentation index at: https://docs.patrimonion.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> Formato padrão de erros e status codes da API.

## Formato de Erro

Todos os erros seguem o mesmo formato JSON:

```json theme={null}
{
  "error": "Descrição legível do problema."
}
```

Sem envelope, sem array, sem campo `code` separado — só `error` com a mensagem. Isso mantém o tratamento simples no frontend.

## Status Codes

| Status | Significado    | Quando ocorre                                             |
| ------ | -------------- | --------------------------------------------------------- |
| `200`  | OK             | Leitura ou atualização bem-sucedida                       |
| `201`  | Created        | Recurso criado com sucesso                                |
| `400`  | Bad Request    | Campos obrigatórios faltando ou valor inválido            |
| `401`  | Unauthorized   | Token ausente ou expirado                                 |
| `403`  | Forbidden      | Token válido, mas o recurso pertence a outro usuário      |
| `404`  | Not Found      | Recurso não existe no banco                               |
| `409`  | Conflict       | Violação de unicidade (ex: CPF duplicado, contrato ativo) |
| `500`  | Internal Error | Erro inesperado no servidor — verifique os logs           |

## Exemplos Reais

<CodeGroup>
  ```json 400 — Campo obrigatório faltando theme={null}
  {
    "error": "contratoId, descricao, valor, dataVencimento e tipo são obrigatórios."
  }
  ```

  ```json 400 — Valor de enum inválido theme={null}
  {
    "error": "Tipo inválido. Use: ALUGUEL, CAUCAO, REPARO"
  }
  ```

  ```json 403 — Acesso negado theme={null}
  {
    "error": "Acesso negado a este contrato."
  }
  ```

  ```json 404 — Recurso não encontrado theme={null}
  {
    "error": "Contrato não encontrado."
  }
  ```

  ```json 409 — Conflito de unicidade theme={null}
  {
    "error": "Já existe um locatário cadastrado com esse CPF."
  }
  ```

  ```json 409 — Regra de negócio theme={null}
  {
    "error": "Não é possível excluir um locatário com contrato ativo."
  }
  ```
</CodeGroup>

## Tratamento no Frontend

```typescript theme={null}
const res = await fetch("https://api.patrimonion.com.br/financeiro", {
  method: "POST",
  credentials: "include", // envia o cookie imob_session automaticamente
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

if (!res.ok) {
  const { error } = await res.json();
  // error é sempre uma string legível
  toast.error(error);
  return;
}

const data = await res.json();
```