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

# Erros

> O formato de erro e todos os códigos de erro.

Toda requisição que falha devolve o mesmo envelope JSON:

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

* Decida pelo `code`, que não muda. A `message` é um texto em inglês para quem desenvolve e pode mudar.
* `details` traz contexto extra em alguns códigos, como `required_scope` ou `retry_after_seconds`.
* `request_id` é igual ao header de resposta `x-request-id`. Informe esse valor quando falar com o suporte.

## Códigos

| Status | Código | Significado |
| - | - | - |
| 400 | `BAD_REQUEST` | A query string ou o corpo estão malformados, um parâmetro da query tem um valor inválido (`details.parameter`), ou o corpo tem um campo que a operação não aceita (`details.field`). |
| 400 | `IDEMPOTENCY_KEY_INVALID` | Um registro veio sem o header `Idempotency-Key`, ou a chave tem mais de 128 caracteres ou caracteres não aceitos. Veja [Idempotência](https://docs.visorfinance.app/pt-BR/idempotency.md). |
| 401 | `UNAUTHENTICATED` | Falta o header `Authorization: Bearer`. |
| 401 | `INVALID_TOKEN` | O token está malformado, não existe ou o segredo está errado. |
| 401 | `TOKEN_EXPIRED` | O token expirou. Crie outro. |
| 401 | `TOKEN_REVOKED` | O token foi revogado. Crie outro. |
| 403 | `PLAN_REQUIRED` | A conta não tem um plano Pro ou Premium ativo. |
| 403 | `INSUFFICIENT_SCOPE` | O token não concede o escopo de `details.required_scope`. |
| 403 | `PIX_UNAVAILABLE` | O Pix pelo Visor não está disponível para a conta. |
| 403 | `PREMIUM_REQUIRED` | Iniciar um Pix exige o plano Premium. `details.url` abre a página do plano. |
| 404 | `NOT_FOUND` | O caminho não existe, ou o espaço ou o recurso não existe ou você não tem acesso a ele. |
| 406 | `NOT_ACCEPTABLE` | O header `Accept` não inclui `application/json`. |
| 409 | `IDEMPOTENCY_CONFLICT` | A `Idempotency-Key` já foi usada na conta para outra transação ou outro Pix. |
| 409 | `IMMUTABLE_PROVIDER_FIELD` | A edição muda um campo que pertence ao banco. `details.field` informa o campo. |
| 409 | `TRANSACTION_CONFLICT` | Outro registro depende da transação, como uma parcela paga. `details.reason` informa o motivo. |
| 409 | `PIX_START_FAILED` | O Pix não pôde começar com esta `Idempotency-Key`, por exemplo porque o rascunho expirou. Envie uma chave nova. |
| 422 | `VALIDATION_FAILED` | O corpo tem valores inválidos. `details.errors` lista cada `field` e `message`. |
| 422 | `AMBIGUOUS_PIX_KEY` | A chave Pix pode ser um CPF ou um celular. Envie a requisição de novo com `key_type`. |
| 422 | `PIX_MONTHLY_LIMIT_REACHED` | O limite mensal de Pix do plano acabou. `details.limit` e `details.renews_on` dizem quando ele renova. |
| 422 | `CPF_REQUIRED` | O perfil do Visor não tem CPF, que o Pix exige. |
| 422 | `BANK_REQUIRED` | Envie o `bank` de onde o Pix sai. `details.banks` lista sugestões. |
| 422 | `BANK_NOT_FOUND` | O Pix pelo Visor não está disponível nesse banco. `details.banks` lista sugestões. |
| 429 | `RATE_LIMITED` | Requisições demais. Veja [Limites de requisição](https://docs.visorfinance.app/pt-BR/rate-limits.md). |
| 500 | `INTERNAL_ERROR` | Aconteceu um erro inesperado. Tente de novo mais tarde. |


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