Error codes
All API errors return { success: false, error: { code, message } }.
Error reference
| Error Code | HTTP Status | Description | How to Handle |
|---|---|---|---|
| MISSING_AUTH | 401 | No Authorization header | Add Authorization: Bearer YOUR_KEY header |
| INVALID_KEY | 401 | Key not found or invalid | Check key is correct and from an active app |
| FEATURE_DISABLED | 403 | Feature not enabled on your API app | Enable in Developer Dashboard → App → Overview |
| ACCOUNT_SUSPENDED | 403 | Merchant account suspended | Contact support@watenga.africa |
| KYC_REQUIRED | 403 | KYC not yet approved | Complete KYC in merchant dashboard |
| PHONE_REQUIRED | 400 | Mobile money payment missing phone | Add customerPhone to request |
| INVALID_PHONE | 400 | Invalid Zimbabwe mobile number | Use format +2637XXXXXXXX |
| INSUFFICIENT_FUNDS | 400 | Payout exceeds available balance | Check balance first |
| INVALID_AMOUNT | 400 | Amount format or value invalid | Use "10.00" format, must be > 0 |
| CURRENCY_MISMATCH | 400 | Currency not supported for method | Check supported currencies per gateway |
| GATEWAY_ERROR | 502 | Upstream payment provider error | Retry after a delay |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests | Back off and retry after 60 seconds |
| NOT_FOUND | 404 | Resource not found | Check the ID is correct |
| VALIDATION_ERROR | 400 | Request body validation failed | Check error details array |
| DUPLICATE_REQUEST | 409 | merchantTransactionId already used | Use a unique ID per transaction |
| OTP_EXPIRED | 400 | Agent cashout OTP expired | Request a new cashout |
| LINK_NOT_FOUND | 404 | Payment link slug not found | Check link URL |
| LINK_EXPIRED | 410 | Payment link has expired | Merchant must create a new link |
| LINK_EXHAUSTED | 410 | Payment link max uses reached | Merchant must create a new link |
| TOTP_REQUIRED | 403 | 2FA code required | Include 6-digit code in X-TOTP-Code header |
| TOTP_INVALID | 403 | 2FA code incorrect or expired | Re-enter from authenticator app |