--- title: Error Code Registry description: Error codes the RizPay Developer API can return and how to handle them. --- These are the error codes the RizPay Developer API can return, grouped by the HTTP status they accompany. A few Developer API codes are returned as literal strings and are documented in [Error Handling](/docs/getting-started/errors): `AUTHENTICATION_REQUIRED`, `ENVIRONMENT_MISMATCH`, `PURCHASE_NOT_FOUND`, and `INVALID_STATUS`. For the Developer API response format and the codes you are most likely to encounter when integrating, start with [Error Handling](/docs/getting-started/errors). Each code is a stable, machine-readable identifier returned in `error.code`. Match on the code, never on the message text: messages can change, codes do not. ## How to read this page - **Code**: the machine-readable identifier returned in `error.code`. - **Description**: what triggers the error. - **User-facing message**: the message shown to end users where one is mapped. Codes without a mapped message return a context-specific message. - The HTTP status in each section heading is the `status.code` the API returns for codes in that section. ## Authentication Errors (HTTP 401) | Code | Description | User-facing message | | --------------------- | -------------------------------------------------- | ----------------------------------------------------------------- | | `AUTH_REQUIRED` | No authentication token provided | Please sign in to continue. | | `INVALID_CREDENTIALS` | Wrong email/password combination | The email or password you entered is incorrect. Please try again. | | `TOKEN_EXPIRED` | JWT token has expired | - | | `TOKEN_REVOKED` | Token has been revoked (user logged out elsewhere) | - | ## Authorization Errors (HTTP 403) | Code | Description | User-facing message | | -------------------- | ------------------------------- | ------------------------------------------------- | | `FORBIDDEN` | General authorization failure | You don't have permission to perform this action. | | `INSUFFICIENT_SCOPE` | API client lacks required scope | - | | `API_DISABLED` | Account API access turned off | - | | `IP_NOT_ALLOWED` | IP not in whitelist | - | ## Validation Errors (HTTP 400) | Code | Description | User-facing message | | ---------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `VALIDATION_ERROR` | General validation failure | Please check your input and try again. | | `MISSING_PARAMETER` | Required field not provided | Some required information is missing. Please provide all required details and try again. | | `INVALID_PARAMETER` | Field value fails validation | - | | `INVALID_PHONE_NUMBER` | Initiation called with a missing or malformed phone number | That doesn't look like a valid phone number. Please check it and try again. | | `INVALID_AMOUNT` | Invalid amount value | - | | `DUPLICATE_REFERENCE` | Duplicate transaction reference | - | ## Resource Not Found Errors (HTTP 404) | Code | Description | User-facing message | | ----------------------- | --------------------------------- | ------------------------------------------------------------------- | | `NOT_FOUND` | Generic not found | - | | `TRANSACTION_NOT_FOUND` | Transaction doesn't exist | This transaction could not be found. | | `PRODUCT_NOT_FOUND` | Product doesn't exist or inactive | This product is no longer available. Please select a different one. | ## Rate Limiting Errors (HTTP 429) | Code | Description | User-facing message | | --------------------- | ---------------------- | --------------------------------------------------------------------------------- | | `RATE_LIMIT_EXCEEDED` | General rate limit hit | For your security, we've paused new attempts. Please wait a moment and try again. | ## Financial Transaction Errors (HTTP 400) | Code | Description | User-facing message | | ---------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | `INSUFFICIENT_BALANCE` | Account balance too low | You don't have enough funds. Please top up your wallet and try again. | | `TRANSACTION_FAILED` | General transaction failure | We couldn't complete your transaction. Please try again, and contact support if you were charged. | | `PURCHASE_FAILED` | Purchase processing failed | - | | `PRODUCT_UNAVAILABLE` | Product or provider down. | This product is currently unavailable. Please try again later or choose a different option. | | `PROVIDER_PRICE_CHANGED` | Provider price has changed since product was last synced - user must retry | This product's price has been updated. Please go back and try again. | | `PROVIDER_ERROR` | External provider failure | - | | `TRANSACTION_LIMIT_EXCEEDED` | Amount over limit | - | | `INVALID_STATUS` | Wrong transaction status for action | - | ## Server Errors (HTTP 500) | Code | Description | User-facing message | | --------------------- | --------------------- | --------------------------------------------------------------------------------------------- | | `INTERNAL_ERROR` | Unhandled exception | Something went wrong on our end. Please try again. If the problem continues, contact support. | | `SERVICE_UNAVAILABLE` | External service down | This service is no longer available. Please choose a different option. | ## Next Steps - [Error Handling](/docs/getting-started/errors) - Developer API response format and handling patterns - [Sandbox Testing](/docs/core-concepts/sandbox) - Trigger errors safely while testing - [Rate Limiting](/docs/core-concepts/rate-limiting) - Understand 429 responses