Error Handling Best Practices

A robust client treats errors as routine. Here is the minimum every integration should implement.

Anatomy Of An Error

Every error response carries:

• An HTTP status code indicating the broad class of problem (see HTTP Status Codes).
• A responseCode field with a Pagamio business code (see Error Code Reference).
• A responseMessage field with a human-readable message safe to log (but not always safe to show end customers verbatim).

{
  "responseCode": "1009",
  "responseMessage": "This product is not available for your account"
}

Decision Tree

When a request fails, use this tree:

1. Is the HTTP status 401? Refresh your token. Retry the original request once. If it fails again, treat as terminal and re-authenticate from scratch.
2. Is it 403? Stop. The caller is not allowed to perform the action. Common causes: a Partner/Vendor token calling /purchase, or a product that isn't active for the merchant.
3. Is it 429? Back off (see Rate Limiting) and retry.
4. Is it 4xx with a business responseCode? Look the code up in the Error Code Reference. If it is in the validation/account class, fix the input — do not retry blindly.
5. Is it 5xx or a network error? Retry with exponential backoff (same merchantReference). After retries, poll /transactions for the final state.

Surface Errors Safely

• Log everything (status, code, message, your merchantReference, the transactionId if returned). You will need this for support.
• Show end customers a short, friendly message. Do not expose responseMessage directly — some messages contain operational detail (e.g. balance amounts).
• Never log the user's full credentials, tokens, or sensitive customer data. See Data Protection.

Specific Errors Worth Handling Explicitly

Code	Handling
1005	Format the mobile number to +27... before resubmitting.
1009	Re-fetch the catalog. Tell the user the product isn't available; contact account manager.
1103	Stop. Wallet/account balance is insufficient. Top up.
1204	Provider timeout. Poll /transactions for the actual outcome before retrying.
1006	Duplicate — you already submitted this transaction. Look up the original by merchantReference.

For the full list, see the Error Code Reference.

---

Last updated: April 2026