Códigos de erro

A API PayerScan utiliza um formato de resposta de erro padronizado. Todos os erros seguem uma estrutura consistente para fácil tratamento no backend do comerciante.

Estrutura de resposta de erro

{
  "status": "error",
  "message": "Invalid API key. Please check your API key and try again.",
  "error_code": "INVALID_API_KEY",
  "request_id": "ORDER_123456",
  "details": { ... }
}

Propriedades:

• status: Sempre "error".
• message: Descrição do erro legível por humanos.
• error_code: Código legível por máquina no formato UPPER_SNAKE_CASE. Use switch/case para tratamento automatizado.
• request_id (opcional): Seu ID de pedido, retornado apenas se fornecido ao criar a fatura.
• details (opcional): Contexto adicional sobre o erro (ex.: erros de validação, nomes dos campos).

Referência de códigos de erro

Erros de autenticação

Código de erro	HTTP	Message	Resolução
MISSING_API_KEY	401	Missing API key. Please provide x-api-key header.	Adicione o header x-api-key à sua requisição.
INVALID_API_KEY	401	Invalid API key. Please check your API key and try again.	Verifique sua API key no Dashboard.
ACCOUNT_INACTIVE	403	Merchant account is inactive. Please contact support to reactivate.	Entre em contato com o suporte PayerScan.
STORE_INACTIVE	403	Store is inactive. Please contact support to reactivate your store.	Reative a loja no Dashboard.
AUTHENTICATION_FAILED	500	Authentication failed. Please try again later.	Tente novamente mais tarde; se persistir, entre em contato com o suporte.

Erros de validação

Código de erro	HTTP	Message	Resolução
VALIDATION_ERROR	400	Validation failed. Please check your request body.	Verifique details.errors para problemas específicos dos campos.
INVALID_MERCHANT_ID	400	Invalid merchant_id. The merchant_id does not match your API key.	Certifique-se de que merchant_id corresponde à loja da API key.

Erros de lógica de negócio

Código de erro	HTTP	Message	Resolução
INSUFFICIENT_BALANCE	402	Insufficient balance. Please top-up your account to continue.	Recarregue no Dashboard PayerScan. Verifique details para o valor em falta.
NO_PAYMENT_METHOD	400	No payment method configured. Please add at least one wallet or exchange platform.	Adicione uma carteira ou conecte uma plataforma de câmbio no Dashboard.

Erros de fatura

Código de erro	HTTP	Message	Resolução
INVOICE_NOT_FOUND	404	Invoice not found.	Verifique o trans_id e certifique-se de que pertence à sua loja.
MISSING_TRANS_ID	400	Missing trans_id in URL.	Inclua trans_id no caminho da URL: GET /invoice/:trans_id.
INVALID_TRANS_ID_FORMAT	400	Invalid trans_id format.	Use o formato correto: TID-XXXXXXXXXXXXXXXX.

Erros de limite de taxa

Código de erro	HTTP	Message	Resolução
RATE_LIMIT_EXCEEDED	429	Too many requests per second. / Rate limit exceeded.	Aguarde retry_after_seconds e tente novamente. Consulte Limites de taxa.

Erros de servidor

Código de erro	HTTP	Message	Resolução
INTERNAL_ERROR	500	Internal server error. Please try again later.	Tente novamente com exponential backoff. Se persistir, entre em contato com o suporte.