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

# Errors

> The error envelope and every error code.

Every failed request returns the same JSON envelope:

```json theme={null}
{
  "errors": [
    {
      "code": "INVALID_TOKEN",
      "message": "The personal API token is not valid.",
      "details": {},
      "request_id": "F8x2kQ9vXc1AAAAB"
    }
  ]
}
```

* Branch on `code`; it is stable. `message` is English text for developers and can change.
* `details` carries extra context for some codes, such as `required_scope` or `retry_after_seconds`.
* `request_id` matches the `x-request-id` response header. Include it when you contact support.

## Codes

| Status | Code | Meaning |
| - | - | - |
| 400 | `BAD_REQUEST` | The query string or body is malformed, a query parameter has an invalid value (`details.parameter`), or the body has a field the operation does not accept (`details.field`). |
| 400 | `IDEMPOTENCY_KEY_INVALID` | A create has no `Idempotency-Key` header, or the key is longer than 128 characters or has other characters. See [Idempotency](https://docs.visorfinance.app/idempotency.md). |
| 401 | `UNAUTHENTICATED` | The `Authorization: Bearer` header is missing. |
| 401 | `INVALID_TOKEN` | The token is malformed, unknown, or its secret is wrong. |
| 401 | `TOKEN_EXPIRED` | The token expired. Create a new one. |
| 401 | `TOKEN_REVOKED` | The token was revoked. Create a new one. |
| 403 | `PLAN_REQUIRED` | The account does not have an active Pro or Premium plan. |
| 403 | `INSUFFICIENT_SCOPE` | The token does not grant the scope in `details.required_scope`. |
| 403 | `PIX_UNAVAILABLE` | Pix payments are not available for the account. |
| 403 | `PREMIUM_REQUIRED` | Starting a Pix needs the Premium plan. `details.url` opens the plan page. |
| 404 | `NOT_FOUND` | The path does not exist, or the space or resource does not exist or is not accessible to you. |
| 406 | `NOT_ACCEPTABLE` | The `Accept` header excludes `application/json`. |
| 409 | `IDEMPOTENCY_CONFLICT` | The `Idempotency-Key` was already used in the account for a different transaction or Pix. |
| 409 | `IMMUTABLE_PROVIDER_FIELD` | An edit changes a field that the bank owns. `details.field` names it. |
| 409 | `TRANSACTION_CONFLICT` | Another record depends on the transaction, such as a paid installment. `details.reason` names it. |
| 409 | `PIX_START_FAILED` | The Pix could not start with this `Idempotency-Key`, for example because its draft expired. Send a new key. |
| 422 | `VALIDATION_FAILED` | The body has invalid values. `details.errors` lists each `field` and `message`. |
| 422 | `AMBIGUOUS_PIX_KEY` | The Pix key can be a CPF or a phone. Send the request again with `key_type`. |
| 422 | `PIX_MONTHLY_LIMIT_REACHED` | The plan's monthly Pix limit is spent. `details.limit` and `details.renews_on` say when it renews. |
| 422 | `CPF_REQUIRED` | The Visor profile has no CPF, which a Pix needs. |
| 422 | `BANK_REQUIRED` | Send the `bank` the Pix comes from. `details.banks` lists suggestions. |
| 422 | `BANK_NOT_FOUND` | Pix through Visor is not available from that bank. `details.banks` lists suggestions. |
| 429 | `RATE_LIMITED` | Too many requests. See [Rate limits](https://docs.visorfinance.app/rate-limits.md). |
| 500 | `INTERNAL_ERROR` | An unexpected error occurred. Retry later. |


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