Error handling
Every Paga API answers in two layers: the HTTP status says whether your request was accepted, and a response code in the body says what happened to the transaction. Handle both and you’ll never mistake a pending payment for a failed one.
The one rule to remember. A response/status code of 0 means success. Every other code needs looking up in the code list for that API before you act: some mean failed, but others mean pending, duplicate reference or another in-between state. An HTTP 200 on its own is not a success.
How to read any response
Use the same three checks for every API. Only the field names differ.
Check the HTTP status
401, 400, 403 or 500 means the request itself failed. See HTTP errors.
Read the response code in the body
statusCodeLook the code up in that API’s code list, then act on what it meansponseCode` for the Business API and Merchant Services.
Act on the code
Look the code up in that API’s code list, then act on what it means.
Code 0. Fulfil the order or credit the customer.
<PagaTile labelLook it up" tone="failed">
Any other code. Check the code list before acting: it may mean failed, pending or duplicate. Never refund or resend on a non-zero code alonh the same reference. Don’t retry.
Any other code. Check the code list before acting: it may mean failed, pending or duplicate. Never refund or resend on a non-zero code alone.
Response codes by API
Each API family has its own code list, which says what every code means and which ones are pending. Look up codes for the endpoint you called.
| Endpoints | Code field | Code list |
|---|---|---|
| Collect API and Direct Debit | statusCode | Collect API status codes |
| Business API | responseCode | Business API error codes |
| Merchant Services and Merchant Notification API | responseCode | Merchant Service API error codes |
HTTP errors
These come before any response code. The request didn’t reach the point where a transaction could be processed.
| Status | What it means | What to do | Retry? |
|---|---|---|---|
401 Unauthorized | Wrong keys, or keys that don’t match the environment’s base URL | Check keys and base URL. See Authentication | After fixing |
400 Bad Request | A value broke a validation rule. Most often the hash | Recreate the hash with the exact values and order. Check required fields | After fixing |
403 Forbidden | Request came from an IP address that isn’t whitelisted | Add the server’s IP. See IP whitelisting | After fixing |
500 Internal Server Error | Paga couldn’t process the request | Check status first, then retry with backoff. Contact support if it continues | Yes, carefully |
{
"error": "Invalid paga account id or password"
}Situations you should always handle
These come up across products. Find the matching code in the code list for your endpoint, and plan a response for each before you go live.
| Situation | What to do |
|---|---|
| Duplicate reference | Don’t resend. The first request may have succeeded. Check status with the original reference |
| Insufficient balance | Stop and alert your team to fund the account. Retrying won’t help |
| Account or transaction limit | Split the amount or ask Paga to review your limits |
| Invalid bank or account | Ask the customer to check their details. Validate accounts before paying out |
| Reference too long | Keep references to 50 characters or fewer |
| Partial payment | The customer paid less than requested. Decide whether to accept, top up, or refund |
| Unknown error | Treat as pending, not failed. Check status before doing anything else |
Retries and duplicate payments
Most double payments happen when a request times out and gets sent again. Your reference number is what prevents it.
One reference per transaction
Give every transaction a unique referenceNumber of up to 50 characters, and store it before you send the request.
Timed out? Check, don’t resend
If you get no response, check status with the same reference. Only send a new request if Paga has no record of it.
Retry with backoff
For HTTP 500s, wait a few seconds and double the wait each time. See Best practices.
Never retry a final failure
Fix the cause first, such as funding the account or correcting details, then start a new transaction with a new reference.
Show customers a clear message, not the raw errorMap each code to a message your customers understand, and log the full response, including the reference number, so your team and Paga support can trace it.
Need help? We’re here 24/7
Talk to our support team any time, or ask questions in the developer community.
Updated about 21 hours ago