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

# Erros

> Como entender erros da API Veepag e encontrar o próximo passo com mais clareza.

Nem sempre uma chamada vai funcionar de primeira, e tudo bem. Esta página ajuda você a entender o que aconteceu e qual caminho seguir para corrigir a integração.

Na maior parte dos casos, os erros da API Veepag indicam uma destas situações: credencial ausente, permissão insuficiente, empresa inacessível, payload inválido ou uma regra de negócio que impediu a operação.

## Formato padrão

```json theme={null}
{
  "error_messages": [
    {
      "msg": "Unauthorized.",
      "type": "field",
      "path": "companyId",
      "location": "body"
    }
  ],
  "code": "unauthorized",
  "path": "/v1/transaction",
  "metadata": {}
}
```

O campo `code` é o melhor ponto de partida para tratar erros de forma programática. Já o campo `error_messages` traz detalhes que ajudam a entender qual campo ou regra precisa de atenção.

## Códigos HTTP

| Status | Code comum                                    | Causa                                                    |
| ------ | --------------------------------------------- | -------------------------------------------------------- |
| `400`  | `ZodValidationException` ou código de domínio | Payload, query string ou regra de negócio inválida.      |
| `401`  | `unauthorized`                                | `apiKey` ou `token` ausente ou inválido.                 |
| `403`  | `forbidden`                                   | Credencial sem acesso à empresa ou permissão solicitada. |
| `404`  | `company_not_found`, `transaction_not_found`  | Recurso não encontrado.                                  |
| `500`  | `unknown_server_error`                        | Erro não mapeado no servidor.                            |

## Erros de negócio comuns

| Code                            | O que aconteceu                                                  | Como resolver                                                                  |
| ------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `company_disabled`              | Empresa ou seller inativo.                                       | Confirme se a empresa está ativa e liberada para operar.                       |
| `payment_method_already_exists` | Cartão já vinculado a outro cliente.                             | Confira se o cartão foi cadastrado para o cliente correto.                     |
| `attempt_limit_exceeded`        | Limite de cartões por cliente excedido em produção.              | Revise os meios de pagamento salvos antes de tentar cadastrar outro.           |
| `integration_access_not_found`  | Integração de pagamento ausente para a empresa.                  | Confirme as integrações configuradas para a empresa.                           |
| `transaction_not_found`         | Transação não encontrada para captura, cancelamento ou consulta. | Confira `transactionId`, `tid`, empresa e ambiente.                            |
| `acquirer_not_found`            | Adquirente não encontrada para a operação.                       | Verifique a configuração de rotas/adquirentes da empresa ou produto.           |
| `product_not_found`             | Produto inexistente ou inacessível.                              | Confira o `productId` e se a credencial tem acesso à empresa do produto.       |
| `client_not_found`              | Cliente inexistente ou inacessível.                              | Confira o `clientId` e a empresa vinculada ao cliente.                         |
| `client_already_exists`         | Cliente já cadastrado.                                           | Use o cliente existente ou busque pelo documento antes de criar outro.         |
| `invalid_client_birth`          | Data de nascimento inválida.                                     | Envie uma data válida no cadastro do cliente.                                  |
| `charge_not_found`              | Cobrança inexistente ou inacessível.                             | Confira `_id`/`chargeId`, empresa e ambiente.                                  |
| `charge_attempt_already_made`   | Tentativa de cobrança já realizada.                              | Consulte a cobrança/transação atual antes de tentar pagar novamente.           |
| `subscription_not_found`        | Assinatura inexistente ou inacessível.                           | Confira `subscriptionId`, empresa e ambiente.                                  |
| `subscription_already_exists`   | Assinatura já cadastrada.                                        | Evite criar duplicidade; consulte a assinatura existente.                      |
| `payment_already_made`          | Pagamento já realizado.                                          | Atualize seu sistema com o pagamento existente em vez de reenviar a tentativa. |
| `invalid_cvv`                   | CVV inválido.                                                    | Solicite ao cliente a revisão dos dados do cartão.                             |
| `bad_request`                   | Regra de negócio ou payload inválido.                            | Leia `error_messages` para entender o detalhe da falha.                        |
| `invalid_captcha`               | Token de captcha inválido no fluxo que exige captcha.            | Gere um novo token e refaça a chamada.                                         |
| `token_expired`                 | Token expirado.                                                  | Gere ou solicite um novo token antes de chamar a API.                          |

## Como investigar

<Steps>
  <Step title="Confira a autenticação">
    Se o status for `401`, confirme se o header `apiKey` ou `token` foi enviado e se pertence ao mesmo ambiente da URL usada.
  </Step>

  <Step title="Confira o acesso à empresa">
    Se o status for `403`, revise o `companyId` e as permissões da credencial. A API valida o acesso por empresa e por recurso.
  </Step>

  <Step title="Revise o payload">
    Se o status for `400`, leia `error_messages`. Falhas de validação usam Zod e podem indicar o campo, o path e a localização do problema.
  </Step>

  <Step title="Valide os IDs enviados">
    Se o status for `404`, confirme se o recurso existe, se pertence à empresa acessada e se o ID correto está sendo usado.
  </Step>
</Steps>

<Tip>
  Ao abrir um chamado com o time Veepag, envie o endpoint chamado, o horário aproximado, o `companyId`, o `code` retornado e o payload de erro. Isso ajuda a gente a investigar com mais rapidez e cuidado.
</Tip>