Skip to main content
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

StatusCode comumCausa
400ZodValidationException ou código de domínioPayload, query string ou regra de negócio inválida.
401unauthorizedapiKey ou token ausente ou inválido.
403forbiddenCredencial sem acesso à empresa ou permissão solicitada.
404company_not_found, transaction_not_foundRecurso não encontrado.
500unknown_server_errorErro não mapeado no servidor.

​
Erros de negócio comuns

CodeQuando pode ocorrer
company_disabledEmpresa ou seller inativo.
payment_method_already_existsCartão já vinculado a outro cliente.
attempt_limit_exceededLimite de cartões por cliente excedido em produção.
integration_access_not_foundIntegração de pagamento ausente para a empresa.
transaction_not_foundTransação não encontrada para captura, cancelamento ou consulta.
product_not_foundProduto inexistente ou inacessível.
client_not_foundCliente inexistente ou inacessível.
charge_not_foundCobrança inexistente ou inacessível.

​
Como investigar

1

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

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

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

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.