Error Code Reference

This page provides a complete reference of all error codes you may encounter when integrating with the Pagamio VAS API.

Error Response Format

All errors follow this standard format:

{
  "success": false,
  "error": {
    "code": 1103,
    "message": "Insufficient balance to proceed with the transaction"
  }
}

Error Code Categories

General Errors (0-999)

Code	Message	Action
0	Purchase successful	N/A
999	Purchase failed	Check specific error details

Validation Errors (1000-1099)

Code	Message	Action
1000	Product not supported	Verify product code
1001	Required fields missing	Check request payload
1002	Product inactive	Product temporarily unavailable
1003	Product not available on channel	Check channel configuration
1004	Invalid purchase amount	Verify amount limits
1005	Invalid phone number format	Check number format (+27...)
1006	Duplicate transaction found	Check if already processed
1007	Invalid tender amount	Verify amount and limits
1008	Invalid fields format	Check meter, phone number, or other fields
1010	Invalid product	Ensure product is valid and supported

Account Errors (1100-1199)

Code	Message	Action
1100	Invalid account details	Verify account information
1101	Account not found	Check account number
1102	Customer not found	Verify customer details
1103	Insufficient balance	Top up account
1104	Invalid meter number	Verify meter number
1105	Customer blocked	Contact support
1106	Customer has arrears	Clear arrears or contact support
1107	Meter request not allowed	Check if meter supports requested operation

Provider Errors (1200-1299)

Code	Message	Action
1200	Provider processing error	Retry transaction
1201	Provider system error	Wait and retry
1202	Provider unavailable	Try again later
1203	Transaction failed at provider	Contact support
1204	Transaction timeout	Check status before retry
1205	Already processed	Verify transaction history
1206	Out of stock	Verify product availability

Common Error Scenarios

Error 1005: Invalid Phone Number Format

Problem: Mobile number is not in the correct format.

Solution:

// ❌ Wrong
mobileNumber: "0821234567"
mobileNumber: "27821234567"

// ✅ Correct
mobileNumber: "+27821234567"

Error 1103: Insufficient Balance

Problem: Merchant account doesn't have enough balance.

Solution:

• Top up your merchant account
• Contact your account manager
• Check your account balance via the portal

Error 1204: Transaction Timeout

Problem: Provider took too long to respond.

Solution:

// Check transaction status before retrying
const status = await checkTransactionStatus(transactionId);
if (status !== 'COMPLETED') {
  // Retry or handle accordingly
}

Error 1006: Duplicate Transaction

Problem: Same transaction was submitted multiple times.

Solution:

• Use unique transaction references
• Implement idempotency keys
• Check transaction history before retrying

Error Handling Best Practices

1. Always Check Error Codes - Don't rely solely on HTTP status
2. Implement Retry Logic - For 1200-1299 errors (provider issues)
3. Log All Errors - Include error code, message, and request details
4. Display User-Friendly Messages - Don't expose raw error messages to users
5. Monitor Error Rates - Track which errors occur most frequently

Related Pages

• HTTP Status Codes - Detailed HTTP status information
• Troubleshooting Guide - Step-by-step debugging
• Common Issues - Frequently encountered problems

---

Last updated: October 2025