Troubleshooting
13.1 Symptom → cause → fix
| Symptom | Likely cause | Fix |
|---|---|---|
401 on every request |
X-Api-Key missing or wrong |
Send the API key on every request, login included |
401 after about 15 minutes |
Token expired | Refresh at 14 minutes; re-login and retry once on 401 (4.2) |
401 straight after login |
Token sent without Bearer , or credentials from the other environment |
Send Authorization: Bearer <token>; match base URL and credentials |
404 on every call |
Wrong base URL, or a missing /api or /bank/api prefix |
Check {baseUrl} and the exact path (7) |
404 on deposit inquiry only |
Path is /bank/api/transaction/inquiry, not /api/... |
Use the /bank prefix |
| Customer is asked for 100 times the amount | Amount sent in dollars instead of cents | Send 450 for US$4.50 (12.1) |
| Tiny amounts (US$0.01) on codes | Amount sent in dollars (1 = 1 cent) |
Multiply by 100 |
Code stays New |
Customer hasn’t paid yet; or the test wallet has no funds | Wait; ask InnBucks to fund the test number |
| Status never recognised | Comparing "Timed Out" exactly, or case-sensitively |
Normalise case and spaces (5.4) |
| Order paid but not fulfilled | Only Paid treated as success |
Treat Claimed and Paid as paid |
| Deep link does nothing | App not installed, or the wrong scheme for the environment | Test scheme for the test app, production scheme for live; keep the code visible |
| QR code image is broken | Missing data:image/png;base64, prefix |
Add the prefix unless qrCode starts with data: |
Linked account inquiry “fails” with 000 |
Checking for 00 only |
Accept 000 as success on that endpoint |
| Duplicate error on deposit | Same reference re-used with duplicate checking enabled |
New reference per deposit; for a lost response use deposit inquiry |
Reversal returns 025 |
Wrong original reference, or already reversed | Check with deposit inquiry first |
Reversal returns 096 |
Temporary failure at InnBucks | Retry later (6.4) |
| Bank change rejected | Amount over US$5, or bank change not enabled | Keep USD at 500 cents or less; ask InnBucks |
| Statement request rejected | Period longer than a calendar month, or a wrong date format | One month at a time; yyyy-MM-dd HH:mm:ss |
Generate WITHDRAWAL fails |
Your account is not an agent account | Ask InnBucks to enable withdrawals |
13.2 Debugging tips
- Reproduce the call with cURL (2) or the skill’s CLI (16.6) outside your app.
- Print the whole response body: the reason is in
responseMsgorresponseDescription. - Keep the
X-Trace-Idof the failing call. - Download the response-code list (7.12) to look up unfamiliar codes.
13.3 Getting help
- UAT submissions (signed form and video): merchants@innbucks.co.zw
- Onboarding and go-live: your InnBucks merchant contact
- Production support: the help-desk contacts InnBucks gives you at go-live training.
Include your merchant name, the environment, the endpoint, your reference, the time, the
responseCode and message, and the X-Trace-Id. Never email your password, API key or
access token.
This page is generated from section 13 of the README in README.md. Spotted something wrong? Open an issue.