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

# Erros

> Formato das respostas de erro e o que fazer em cada código de status.

## Dois formatos de erro

A API retorna erros em JSON, em um de dois formatos.

### Erro geral

Um único campo `detail` com a mensagem:

```json theme={null}
{
  "detail": "As credenciais de autenticação não foram fornecidas."
}
```

### Erro de validação

Um objeto onde cada chave é o campo rejeitado e o valor é a lista de problemas daquele campo:

```json theme={null}
{
  "name": ["Este campo é obrigatório."],
  "price": ["Informe um número válido."]
}
```

<Note>
  As mensagens são retornadas em **português (Brasil)**. Não use o texto da mensagem como regra de negócio — trate pelo código de status e, quando for erro de validação, pelo nome do campo.
</Note>

## Códigos de status

| Código | Significado          | O que fazer                                                                              |
| ------ | -------------------- | ---------------------------------------------------------------------------------------- |
| `200`  | Sucesso              | —                                                                                        |
| `201`  | Recurso criado       | —                                                                                        |
| `204`  | Sucesso sem conteúdo | —                                                                                        |
| `400`  | Requisição inválida  | Corrija o payload. Veja os campos apontados na resposta                                  |
| `401`  | Não autenticado      | Token ausente, inválido ou expirado. Solicite um novo em [Autenticação](/authentication) |
| `403`  | Sem permissão        | O token não tem o escopo necessário para o endpoint                                      |
| `404`  | Não encontrado       | Verifique o identificador. Também ocorre para recursos de outra conta                    |
| `409`  | Conflito             | Chave de idempotência reutilizada. Veja [Idempotência](/conceitos/idempotencia)          |
| `429`  | Limite excedido      | Aguarde o `Retry-After`. Veja [Limites de Requisição](/conceitos/rate-limits)            |
| `500`  | Erro interno         | Tente novamente com backoff. Se persistir, contate o suporte                             |

## Casos que confundem

<AccordionGroup>
  <Accordion title="401 vs 403" icon="key">
    * `401` — a API não sabe quem você é: o token está ausente, malformado ou expirou.
    * `403` — a API sabe quem você é, mas sua chave não tem o **escopo** necessário. Por exemplo, chamar `POST /public_api/products/` com um token que só tem `read`.

    Os escopos de cada endpoint estão indicados na própria página de referência.
  </Accordion>

  <Accordion title="404 em recurso que existe" icon="magnifying-glass">
    Todos os endpoints filtram pelos dados da **sua conta**. Consultar um recurso que pertence a outro produtor retorna `404`, não `403` — isso é intencional, para não revelar a existência do recurso.
  </Accordion>

  <Accordion title="Token expirado no meio de um lote" icon="clock">
    O token tem validade limitada (campo `expires_in`) e **não existe endpoint de renovação**. Ao receber `401` durante um processamento longo, solicite um novo token e repita a requisição.
  </Accordion>

  <Accordion title="Erro 5xx numa cobrança" icon="triangle-exclamation">
    Respostas `5xx` não são armazenadas pela idempotência. Repita a requisição com o **mesmo** `X-Idempotency-Key`: se a cobrança original tiver sido criada, você recebe a resposta original em vez de uma duplicata.
  </Accordion>

  <Accordion title="400 em Pix ou boleto que funciona no cartão" icon="building-columns">
    `POST /public_api/payments/` rejeita `pix`, `pix_auto` e `boleto` com `400` no campo `paymentMethod` quando o produtor não tem conta **Cakto Banking** com abertura concluída, ativa, principal e fora de encerramento — é nela que esses métodos liquidam. `credit_card` e `threeDs` ficam **fora** desse gate — cartão não liquida nessa conta —, mas exigem os campos próprios do cartão (`card` e `antifraud_profiling_attempt_reference`), então trocar só o `paymentMethod` não é um payload válido.

    Não é erro de payload: nenhum ajuste nos campos de Pix ou boleto resolve, o bloqueio é a conta. Conclua ou regularize a abertura da conta no [Painel Cakto](https://app.cakto.com.br/dashboard). Detalhes em [Pré-requisitos](/api-reference/payments/create-pix#pré-requisitos).
  </Accordion>
</AccordionGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="key" href="/authentication">
    Escopos, tokens e expiração
  </Card>

  <Card title="Limites de Requisição" icon="gauge-high" href="/conceitos/rate-limits">
    Como reagir ao 429
  </Card>
</CardGroup>