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

# Errors

> HTTP status codes, stable error codes and how to retry.

Every error is `application/problem+json`, following [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). This covers authentication, validation, rate limits, insufficient balance and unavailable dependencies.

Never parse error text. Branch on:

* `status` for HTTP flow (retry, login, 404)
* `code` for product decisions, the stable identifier
* `errors[].field` to highlight invalid form fields
* `requestId` when contacting support

```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` may be reworded or translated. `code` will not change.

## HTTP status

| Status | Meaning |
| - | - |
| `400` | Invalid parameters |
| `401` | Invalid or missing API key or token |
| `402` | Insufficient balance (live mode only) |
| `403` | The credential lacks permission or scope |
| `404` | Resource not found (or it belongs to the other mode) |
| `409` | State conflict: duplicate phone/CPF, or an `Idempotency-Key` reused with a different payload |
| `429` | Rate limit exceeded |
| `502` | An upstream integration failed |
| `503` | A required integration is not configured or is unavailable |

## Error codes

| `code` | When |
| - | - |
| `VALIDATION_ERROR` | Invalid body, query or path parameter |
| `BAD_REQUEST` | Semantically invalid request |
| `UNAUTHORIZED` | Missing, invalid or expired token |
| `INSUFFICIENT_BALANCE` | Wallet cannot cover a live operation |
| `FORBIDDEN` | Missing role or scope |
| `RESOURCE_NOT_FOUND` | Does not exist, belongs to another organization, or is in the other mode |
| `CONFLICT` | Incompatible state, conflicting idempotency, or duplicate client |
| `RATE_LIMITED` | API key or IP limit reached |
| `MERCADO_PAGO_NOT_CONFIGURED` | Automatic PIX is unavailable for the organization |
| `UPSTREAM_ERROR` | Mercado Pago, OpenAI or storage failed to respond |
| `SERVICE_UNAVAILABLE` | A configured dependency cannot serve the operation |
| `INTERNAL_ERROR` | Unexpected failure, send the `requestId` to support |

## Retries

Use an `Idempotency-Key` on every mutation. Retry automatically only on `429`, `502` and `503`, keeping the same key, and honor `Retry-After` on `429`. Do not retry `404`, `409` or `VALIDATION_ERROR` without fixing the request.


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