Troubleshooting Guide

A decision-tree style guide to diagnosing failed requests.

Step 1: Look At The HTTP Status

Status	Meaning	Where To Look Next
2xx	Request reached the API and was processed	Check responseCode and successful in the body.
400	Bad request	Check the responseMessage and the field you sent.
401	Token missing/expired/invalid	Refresh and retry. If still 401, re-authenticate.
403	Forbidden	Wrong role for endpoint, or product not active for you.
404	Not found	Verify path and any {id} segments.
409	Conflict	Duplicate merchantReference with different content.
429	Rate limited	Backoff and retry.
5xx	Server error	Backoff, retry, then poll for the transaction's actual state.

Step 2: Look At The responseCode

If the HTTP status is 2xx but successful: false, the body will carry a Pagamio business responseCode. Look it up in the Error Code Reference.

The most common ones to handle explicitly:

• 1005 — phone number format wrong.
• 1009 — product not active for your account.
• 1103 — insufficient balance.
• 1204 — provider timeout (poll, don't blind-retry).
• 1006 — duplicate transaction.

Step 3: For Lost / Timed-Out Transactions, Always Poll

If you don't have a definitive answer (network timeout, retries exhausted), call POST /transactions with the merchantReference you used. Treat the platform's view as authoritative.

Step 4: When To Open A Support Ticket

• A transaction has been PROCESSING for over 5 minutes.
• You receive 5xx errors persistently for more than a few minutes.
• You receive a responseCode you cannot find in the Error Code Reference.
• You believe a product should be active for your account but 1009 says otherwise.

When raising a ticket, always include:

• The transactionId (if returned).
• Your merchantReference.
• The full request and response (with credentials redacted).
• Timestamp in SAST.

See Getting Help.

---

Last updated: April 2026