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

# Erros

> Códigos HTTP, códigos de erro estáveis e como fazer retry.

# Erros

Todos os erros da API HTTP e do MCP são `application/problem+json`, conforme [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). Isso inclui autenticação, validação, rate limit, saldo insuficiente e dependências indisponíveis.

Nunca faça parsing de texto de erro. Use:

* `status` para o fluxo HTTP (retry, login, 404)
* `code` para decisões de produto no cliente, no MCP e em automações
* `requestId` ao abrir um chamado de suporte
* `errors[].field` para destacar campos inválidos em formulários

```json theme={null}
{
  "type": "https://docs.payable.run/errors/validation_error",
  "title": "Bad Request",
  "status": 400,
  "detail": "One or more request fields are invalid.",
  "instance": "/api/v1/clients",
  "code": "VALIDATION_ERROR",
  "requestId": "d8a19cda-1086-4b92-99c3-4ea116d72111",
  "errors": [{ "field": "email", "message": "email must be an email" }]
}
```

`detail` pode ser traduzido ou refinado. `code` é o identificador estável.

## Status HTTP

| Status | Quando ocorre |
| - | - |
| `400` | Parâmetros inválidos |
| `401` | API key ou token inválido |
| `402` | Saldo insuficiente (apenas modo live) |
| `403` | A credencial não possui permissão ou escopo para a operação |
| `404` | Recurso não encontrado (ou sandbox mismatch) |
| `409` | Conflito de estado: telefone/CPF duplicado ou Idempotency-Key reutilizada com payload diferente |
| `429` | Rate limit excedido |
| `502` | Uma integração upstream falhou ao atender a operação |
| `503` | Uma integração necessária não está configurada ou está indisponível |

## Códigos de aplicação

| `code` | Quando ocorre |
| - | - |
| `VALIDATION_ERROR` | Corpo, query ou parâmetro de rota inválido |
| `BAD_REQUEST` | A requisição é semanticamente inválida |
| `UNAUTHORIZED` | Token ausente, inválido ou expirado |
| `INSUFFICIENT_BALANCE` | Carteira sem saldo para a operação live |
| `FORBIDDEN` | Sem papel ou escopo necessário |
| `RESOURCE_NOT_FOUND` | Recurso não existe, não pertence à organização ou está em outro modo (live/test) |
| `CONFLICT` | Estado incompatível, incluindo idempotência conflituosa e unicidade de cliente |
| `RATE_LIMITED` | Limite por API key ou IP atingido |
| `MERCADO_PAGO_NOT_CONFIGURED` | PIX automático não está disponível para a organização |
| `UPSTREAM_ERROR` | Mercado Pago, OpenAI ou storage falhou ao responder |
| `SERVICE_UNAVAILABLE` | Uma dependência configurada não pode atender à operação |
| `INTERNAL_ERROR` | Falha inesperada; use `requestId` para suporte |

No TypeScript, leia `error.code` (MCP) ou `error.data.code` (cliente HTTP da web). Não compare `detail`.

## Retries

Use `Idempotency-Key` em todas as mutações. Em `429`, respeite o header `Retry-After`. Só faça retry automático em `429`, `502` ou `503`, mantendo a mesma chave de idempotência para mutações. Não repita `404`, `409` ou `VALIDATION_ERROR` sem corrigir o pedido.


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