Error Handling
If an error occurs, the API returns an appropriate HTTP status code along with an error message in the response body.
HTTP Status Codes
| Status Code | Description |
|---|---|
| 400 | Bad request |
| 401 | Unauthorized access |
| 404 | Transaction not found |
| 500 | Internal server error |
Application-level Errors
Pay-in, pay-out, remittance, and card APIs also return business status codes in the JSON body (e.g. status: "0050"). These are distinct from HTTP status codes.
| Product | Status code reference |
|---|---|
| Pakistan wallet pay-in | Pay-In (wallet — PK) |
| Unified pay-in (BD/NP/EG/IQ) | Pay-In (unified) |
| Cards | Cards |
| Pay-out | Pay-Out |
| Remittance | Remittance |
Recommended Handling
- Check the HTTP status first — retry only on transient
5xxerrors with backoff. - Parse the JSON
statusandmessagefields for business outcomes. - For async flows (non-OTP wallets, disbursements, remittances), combine API responses with webhooks and inquiry APIs for final state.
- Log
reference,transactionId, oruserKeyfor support escalation.