Business API Error Codes
Every Business API response includes a responseCode. 0 means success. Look every other code up here before you act: some mean a transfer is pending, a duplicate or unknown, not failed.
Never send a new reference for an unknown outcomeA new reference pays again. For
-1,105,135and any timeout, check the original reference first, and only start a new transaction once you know the first one failed.
When you can’t tell what happened
Timeouts are unknown outcomes
If a request times out (an HTTP 504, a reset connection or a read timeout) and returns no body, don’t ask your customer to start over. Call transactionStatus with the original reference. If you must recover by resubmitting, use the exact same reference: Paga returns 105 if the first one succeeded, so you can’t pay twice.
Wait 5 seconds before your first status check
Paga’s queue needs a moment to sync. Checking at the same instant as you submit can return a false 135. Wait at least 5 seconds, and remember the status check covers the last 48 hours.
All response codes
Success
| Code | Meaning | What to do |
|---|---|---|
0 | Success | The transaction was processed. |
1 | Bulk money transfer: partial success, or empty request | Treat as success, but go through the items in the response to see which transfers failed. |
Pending
| Code | Meaning | What to do |
|---|---|---|
3 | Pending | The transaction is still processing. Check the transaction status, or for money transfers wait for the notification at your statusCallbackUrl. |
Unknown outcome: check the status first
| Code | Meaning | What to do |
|---|---|---|
-1 | Unknown error | Don’t ask your customer to retry. The request failed, but the transfer may have succeeded. Check the transaction status with the original reference number. For money transfers, you can also wait for the notification. |
105 | Duplicate reference | Don’t retry. Paga has already logged this transaction. Check its status with the reference number, or for money transfers, wait for the notification. |
135 | Unknown reference number | The transaction may have been dropped by validation, or hasn’t synced yet. Resubmit it straight away with the exact same reference number. If Paga returns a validation error, such as Invalid Amount, ask your customer to fix it. If it returns 105 Duplicate reference, the transaction exists, so check its status. |
Failed
Service and integration
| Code | Meaning | What to do |
|---|---|---|
-2 | Unsupported operation | Integration error. Check the API documentation for the supported methods. |
2 | Bulk money transfer: all failed | System or operation error. Safe to ask your customer to retry with a new reference number. |
109 | Buy airtime error | Service-specific error. Safe to retry with a new reference number. |
132 | Invalid process channel | Integration error. The channel isn’t permitted for this operation. |
Validation
| Code | Meaning | What to do |
|---|---|---|
-9 | Invalid process type | Validation error. Check the payload requirements. |
-8 | Missing process type | Validation error. Check the payload requirements. |
-4 | Missing reference number | Validation error. Make sure referenceNumber is sent. |
-3 | Invalid bulk operation size | Validation error. Check the bulk limits and retry. |
116 | Invalid amount | Validation error. Check for negative numbers, invalid formats or missing decimals. |
117 | Missing required parameter | Validation error. Review the documentation for the specific endpoint. |
123 | Invalid phone number | Validation error. Check the length and the country code. |
124 | Invalid first name | Validation error. Make sure there are no special characters or numbers. |
125 | Invalid last name | Validation error. Make sure there are no special characters or numbers. |
126 | Invalid username | Validation error. Check the username rules. |
127 | Invalid email | Validation error. Check the email format. |
130 | Invalid name | Validation error. The name format was rejected. |
134 | Invalid date of birth | Validation error. Check the date format, such as YYYY-MM-DD, and the age rules. |
140 | Reference number exceeds the maximum length of 50 characters | Validation error. Shorten or regenerate the reference number. |
Limits and balance
| Code | Meaning | What to do |
|---|---|---|
136 | Exceeds transaction limit | Limit error. The requested amount is too high. |
137 | Below minimum transaction limit | Limit error. The requested amount is too low. |
138 | Exceeds account limit | Limit error. The account has reached a velocity or volume cap. |
139 | Insufficient balance | Balance error. Fund the source account before retrying. |
Destination account
| Code | Meaning | What to do |
|---|---|---|
4 | Deposit to bank: invalid account number | Destination error. Ask your customer to check the account number. |
101 | Invalid bank | Destination error. The bank code or UUID isn’t recognised. |
103 | Disabled or inactive account | Destination error. The receiving account can’t accept funds. |
107 | Invalid recipient account | Destination error. Ask your customer to check the recipient’s details. |
114 | Invalid account | Destination error. The account is invalid or closed. |
115 | Invalid bank account | Destination error. The account is invalid or closed. |
133 | Can’t find destination bank | Destination error. The bank might be offline or delisted. |
Identity and access
| Code | Meaning | What to do |
|---|---|---|
104 | Invalid principal in use | Authentication error. Check your API credentials or user context. |
106 | Invalid source of funds | Identity error. The specified funding source isn’t allowed. |
108 | Invalid organisation user | Identity error. Check user permissions. |
110 | Invalid organisation | Identity error. Check your merchant or organisation configuration. |
111 | Invalid customer | Identity error. The customer profile can’t be verified. |
112 | Invalid biller name, or the biller service doesn’t exist | Identity error. The biller might be decommissioned or misspelled. |
113 | Invalid user | Identity error. The user profile can’t be verified. |
118 | Invalid user identifier | Identity error. Check the format of the ID you’re sending. |
119 | Invalid process | Identity or system error. The requested workflow is invalid. |
129 | Locked user account | Security error. The account needs unlocking by Paga support. |
131 | Invalid merchant | Identity error. The merchant account can’t be verified. |
Customer profile and KYC
| Code | Meaning | What to do |
|---|---|---|
120 | Photo already set | User profile error. An existing photo can’t be overwritten with this flow. |
121 | Invalid image type | User profile error. Make sure the image is a supported format, such as JPG or PNG. |
122 | Invalid identification details | KYC error. The ID details don’t match, or are invalid. |
128 | Email already exists | User profile error. Ask your customer to log in or use a different email. |
Got a code that isn’t listed? Treat it as an unknown outcome: check the transaction status with the original reference, and contact support with the reference if it stays unclear.
Related
Error handling
The rules that apply to every API, including HTTP errors and retries. Read the guide.
Checking a transaction
Each payout guide ends with “Check the transaction status”, for example Money transfer and Bill payment.
Notifications
Money transfers send a notification to your statusCallbackUrl when they’re processed. Airtime, data and bill payments don’t, so check their status instead.
Need help? We’re here 24/7
Talk to our support team any time, or ask questions in the developer community.
Updated 3 days ago