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

# Erros e códigos

> Todos os códigos de erro da API, com o status HTTP e o que fazer em cada um.

Esta página é para o desenvolvedor que recebeu um erro e quer resolver rápido.

## O formato

Erro vem em `error`, como objeto. Erros de negócio trazem `codigo`, um identificador
estável para o seu código tratar — a `message` é para gente, pode mudar de texto:

```json theme={null}
{ "error": { "message": "…", "codigo": "VALOR_MINIMO", "valor_minimo": 5 } }
```

Duas exceções para conhecer:

* **Autenticação**: quando a credencial falha (401), `error` é uma **string**, não um
  objeto: `{ "error": "Token JWT ou chave de API ausente" }`. Trate os dois formatos.
* **Erro inesperado (500)**: a resposta traz um `id` de correlação
  (`{ "error": { "message": "Erro interno… informe o código a1b2c3d4.", "id": "a1b2c3d4" } }`).
  Informe esse código ao suporte — ele liga a sua chamada ao log exato.

## Os códigos

| `codigo`                   | Status                  | Onde acontece                                                                                      | O que fazer                                                                                                   |
| -------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `PRODUCAO_NAO_LIBERADA`    | 409 (403 em chave live) | qualquer operação de produção antes da aprovação                                                   | complete a [aprovação de produção](/aprovacao-de-producao); o bloco `producao` da resposta diz em que pé está |
| `CADASTRO_INCOMPLETO`      | 400                     | `POST /producao/solicitar`                                                                         | complete os campos de `faltando` e envie os documentos de `documentos_faltando`                               |
| `STATUS_NAO_PERMITE`       | 409                     | mexer em documentos com o cadastro em análise/aprovado; aprovar ou recusar quem não está `pending` | espere a análise terminar (ou confira o status atual em `GET /producao`)                                      |
| `SOMENTE_PAINEL`           | 403                     | enviar documentos com chave de API                                                                 | use a sessão do painel — documento não viaja por chave                                                        |
| `SOMENTE_TITULAR`          | 403                     | membro de loja compartilhada mexendo no cadastro de produção do dono                               | só o titular envia o próprio cadastro                                                                         |
| `SOMENTE_ADMIN`            | 403                     | rotas da equipe V4 Pay (aprovações, edição do Roadmap)                                             | não é para integração — se você deveria ser admin, fale com a equipe                                          |
| `SOMENTE_AUTOR_OU_ADMIN`   | 403                     | apagar comentário do Roadmap que não é seu                                                         | só o autor (ou a equipe) apaga                                                                                |
| `VALOR_MINIMO`             | 400                     | emitir cobrança ou criar link abaixo de **R\$ 5,00** — inclusive quando um cupom derruba o total   | cobre pelo menos R\$ 5,00; a resposta traz `valor_minimo`                                                     |
| `LINK_INDISPONIVEL`        | 409                     | checkout público de um link cujo dono não pode emitir                                              | mensagem neutra para o pagador; o dono vê o motivo real na conta dele                                         |
| `REPASSE_MANUAL`           | 409                     | `POST /withdrawals` no modo conta única                                                            | o saque está suspenso; o repasse é manual — veja [Modo de recebimento](/modo-de-recebimento)                  |
| `MUITAS_REFERENCIAS`       | 409                     | excluir cupom, produto ou assinatura com mais de 500 referências                                   | desative (`is_active`/`active: false` ou `status: canceled`) em vez de excluir — o histórico fica íntegro     |
| `SKU_DUPLICADO`            | 409                     | criar/editar produto com `sku` que você já usa                                                     | troque o `sku` ou edite o produto existente                                                                   |
| `CNPJ_JA_CADASTRADO`       | 409                     | `POST /receiving-account` com CNPJ que já tem subconta                                             | a conta de recebimento desse CNPJ já existe — confira `GET /receiving-account`                                |
| `SUBCONTA_INEXISTENTE`     | 409                     | emitir em produção, no modo subconta, sem ter cadastrado a empresa                                 | complete o cadastro em `POST /receiving-account`                                                              |
| `SUBCONTA_NAO_APROVADA`    | 409                     | emitir com a subconta ainda em análise no motor de pagamentos                                      | veja o bloco `aprovacao` da resposta e o `link_documentos` de `GET /receiving-account`                        |
| `PROVEDOR_NAO_CONFIGURADO` | 500                     | o servidor está sem as credenciais do motor de pagamentos                                          | não é erro seu — avise o suporte                                                                              |

<Note>
  `400` sem `codigo` é validação comum (campo faltando, documento com dígito verificador
  errado, CEP inválido…) — a `message` diz exatamente o quê.
</Note>