Error Codes

PayerScan API uses a standardized error response format. All errors follow a consistent structure for easy handling on the merchant's backend.

Error Response Structure

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

Properties:

• status: Always "error".
• message: Human-readable error description.
• error_code: Machine-readable code in UPPER_SNAKE_CASE format. Use switch/case for automated handling.
• request_id (optional): Your order ID, returned only if provided when creating the invoice.
• details (optional): Additional context about the error (e.g., validation errors, field names).

Error Code Reference

Authentication Errors

Error Code	HTTP	Message	Resolution
MISSING_API_KEY	401	Missing API key. Please provide x-api-key header.	Add x-api-key header to your request.
INVALID_API_KEY	401	Invalid API key. Please check your API key and try again.	Verify your API key on the Dashboard.
ACCOUNT_INACTIVE	403	Merchant account is inactive. Please contact support to reactivate.	Contact PayerScan support.
STORE_INACTIVE	403	Store is inactive. Please contact support to reactivate your store.	Re-enable store on the Dashboard.
AUTHENTICATION_FAILED	500	Authentication failed. Please try again later.	Retry later; if persistent, contact support.

Validation Errors

Error Code	HTTP	Message	Resolution
VALIDATION_ERROR	400	Validation failed. Please check your request body.	Check details.errors for specific field issues.
INVALID_MERCHANT_ID	400	Invalid merchant_id. The merchant_id does not match your API key.	Ensure merchant_id matches the API key's store.

Business Logic Errors

Error Code	HTTP	Message	Resolution
INSUFFICIENT_BALANCE	402	Insufficient balance. Please top-up your account to continue.	Top-up on PayerScan Dashboard. Check details for shortage amount.
NO_PAYMENT_METHOD	400	No payment method configured. Please add at least one wallet or exchange platform.	Add a wallet address or connect an exchange platform on the Dashboard.

Invoice Errors

Error Code	HTTP	Message	Resolution
INVOICE_NOT_FOUND	404	Invoice not found.	Verify trans_id and ensure it belongs to your store.
MISSING_TRANS_ID	400	Missing trans_id in URL.	Include trans_id in the URL path: GET /invoice/:trans_id.
INVALID_TRANS_ID_FORMAT	400	Invalid trans_id format.	Use the correct format: TID-XXXXXXXXXXXXXXXX.

Rate Limit Errors

Error Code	HTTP	Message	Resolution
RATE_LIMIT_EXCEEDED	429	Too many requests per second. / Rate limit exceeded.	Wait for retry_after_seconds and retry. See Rate Limits.

Server Errors

Error Code	HTTP	Message	Resolution
INTERNAL_ERROR	500	Internal server error. Please try again later.	Retry with exponential backoff. If persistent, contact support.