Developer Documentation

Error Code Registry

Error Code Registry

| Code | HTTP | Message | Description | Likely cause | App behavior |

| --- | --- | --- | --- | --- | --- |

| UNAUTHENTICATED | 401 | Authentication is required | Missing bearer token | user not logged in | show login |

| INVALID_TOKEN | 401 | Invalid or expired access token | Bad/expired JWT | stale session | refresh or login |

| INVALID_REFRESH_TOKEN | 401 | Invalid refresh token | Refresh token invalid/revoked | stale session | login |

| ACCOUNT_INACTIVE | 403 | Account is not active | suspended/locked/pending | account restriction | show support message |

| PHONE_NOT_VERIFIED | 403 | Phone not verified | onboarding incomplete | OTP pending | prompt verification |

| KYC_REQUIRED | 409 | KYC required | merchant/customer needs KYC | approval pending | show KYC flow |

| MERCHANT_NOT_ACTIVE | 403/404 | Merchant is not active | merchant suspended/pending | invalid merchant | block payment |

| QR_INVALID | 404 | QR invalid | token/code mismatch | bad scan | rescan |

| QR_REVOKED | 409 | QR revoked | old QR used | stale printout | ask merchant new QR |

| INSUFFICIENT_FUNDS | 409 | Insufficient wallet balance | wallet too low | payment/withdrawal impossible | show balance error |

| LIMIT_EXCEEDED | 422 | Transaction limit exceeded | daily/monthly/single limit | compliance limit | show limit |

| INVALID_TRANSACTION_PIN | 403 | Invalid transaction PIN | wrong PIN | user input error | retry/lockout |

| DEVICE_NOT_TRUSTED | 403 | Device not trusted | new/suspicious device | security | verify device |

| PAYMENT_ALREADY_PROCESSED | 409 | Payment already processed | duplicate confirmation | idempotency/status | refresh status |

| WITHDRAWAL_ALREADY_COMPLETED | 409 | Withdrawal already completed | duplicate completion | status conflict | refresh status |

| PROVIDER_UNAVAILABLE | 503 | Provider unavailable | provider outage | external dependency | retry later |

| RATE_LIMITED | 429 | Too many requests | rate limit hit | too many calls | back off |

| WEBHOOK_SIGNATURE_REQUIRED | 401 | Webhook signature required | missing signature | bad provider request | reject |

| INVALID_WEBHOOK_SIGNATURE | 401 | Webhook signature failed | invalid signature | spoof/replay | reject |

| IDEMPOTENCY_KEY_REQUIRED | 400 | Idempotency key required | missing key | client bug | send unique key |

| IDEMPOTENCY_CONFLICT | 409 | Key reused with different body | unsafe duplicate | client bug | generate new key |

| FORBIDDEN | 403 | Permission denied | role/scope denied | insufficient permission | hide action |

| MAINTENANCE_MODE | 503 | Under maintenance | service disabled | planned outage | show maintenance |

| API_KEY_REQUIRED | 401 | API key required | missing key | partner auth error | configure key |

| API_KEY_INVALID | 401 | API key invalid/revoked | bad/revoked key | credential issue | rotate key |

| API_KEY_EXPIRED | 401 | API key expired | expiry passed | old key | create key |

| API_SCOPE_DENIED | 403 | Scope not allowed | missing scope | app not authorized | request scope |

| API_RATE_LIMIT_EXCEEDED | 429 | API key rate limit exceeded | too many partner calls | over quota | back off |

| SANDBOX_DISABLED | 403 | Sandbox tools disabled | production mode | wrong environment | use staging |