Erros

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

{
  "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

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.

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.

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.

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.

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.

Comece aqui

Guias

API Reference

Formato padrão

Códigos HTTP

Erros de negócio comuns

Como investigar

​Formato padrão

​Códigos HTTP

​Erros de negócio comuns

​Como investigar

Formato padrão

Códigos HTTP

Erros de negócio comuns

Como investigar