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

## 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](https://docs.cakto.com.br/authentication.md) |
| `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](https://docs.cakto.com.br/conceitos/idempotencia.md)), ou a conta ainda não está habilitada para a operação — em saldo e saque, significa cadastro de recebimento não concluído no painel |
| `422` | Regra de negócio | O payload é válido, mas a operação não pode ser executada no estado atual da conta — por exemplo, saldo insuficiente para o saque |
| `429` | Limite excedido | Aguarde o `Retry-After`. Veja [Limites de Requisição](https://docs.cakto.com.br/conceitos/rate-limits.md) |
| `500` | Erro interno | Tente novamente com backoff. Se persistir, contate o suporte |
| `503` | Indisponível | Falha temporária ao consultar um serviço interno. Repita com backoff — **em operações que movem dinheiro, repita com a mesma chave de idempotência** |

## Casos que confundem

> [accordion] 401 vs 403
>
> * `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] 404 em recurso que existe
>
> 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] Token expirado no meio de um lote
>
> 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] Erro 5xx numa cobrança
>
> 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.

## Próximos passos

> [card] [Autenticação](https://docs.cakto.com.br/authentication.md)
>
> Escopos, tokens e expiração

> [card] [Limites de Requisição](https://docs.cakto.com.br/conceitos/rate-limits.md)
>
> Como reagir ao 429


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.