Error Code Registry
Every RizPay platform error code, generated from the backend source of truth
Generated reference. This page is generated directly from the central backend error code registry (154 codes). To regenerate it after a backend change, run
yarn docs:errorsfrom the landing project.
A few Partner API specific codes are returned as literal strings outside this
registry: ENVIRONMENT_MISMATCH, PURCHASE_NOT_FOUND, and INVALID_PHONE_NUMBER.
They are documented in Error Handling.
For the Partner API response format and the error codes you are most likely to encounter when integrating, start with Error Handling. This registry is the exhaustive platform-wide list, including codes used by the RizPay consumer apps.
Each code is a stable, machine-readable identifier. 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 responses.
- Description: what triggers the error, from the backend registry.
- 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 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_INVALID | Token not found, malformed, or tampered | - |
TOKEN_REVOKED | Token has been revoked (user logged out elsewhere) | - |
REFRESH_TOKEN_INVALID | Invalid refresh token provided | - |
REFRESH_TOKEN_EXPIRED | Refresh token has expired | - |
PASSKEY_INVALID | WebAuthn credential verification failed | We couldn't verify your passkey. Please try again, or use your password to sign in. |
PASSKEY_NOT_VERIFIED | Passkey pending email verification | This passkey hasn't been verified yet. Please verify it from your email, then try again. |
PASSKEY_UNKNOWN | Unknown passkey credential ID | - |
AUTH_FAILED | General authentication failure | - |
Authorization Errors (HTTP 403)
| Code | Description | User-facing message |
|---|---|---|
FORBIDDEN | General authorization failure | You don't have permission to perform this action. |
FEATURE_UNAVAILABLE | The feature is turned off via a feature flag (ops kill-switch / not yet ramped) | This feature isn't available right now. Please check back soon. |
ACCOUNT_ACCESS_DENIED | User not authorized for account | - |
TRANSACTION_ACCESS_DENIED | User not authorized for transaction | You cannot access this transaction. |
EVENT_ACCESS_DENIED | User not authorized for event | - |
CONVERSATION_ACCESS_DENIED | User not a participant in conversation | - |
PLATFORM_RESTRICTED | Platform restriction enabled (web user tries mobile-only action) | - |
INSUFFICIENT_SCOPE | API client lacks required scope | - |
API_DISABLED | Account API access turned off | - |
IP_NOT_ALLOWED | IP not in whitelist | - |
BUSINESS_ACCOUNT_REQUIRED | Business account required for this feature | - |
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 | - |
MESSAGE_BLANK | Empty conversation message content | Your message is empty. Please type something and try again. |
CONVERSATION_CLOSED | Message sent to a closed conversation | This conversation has been closed, so your message wasn't sent. If you need more help, please start a new conversation. |
MESSAGE_DUPLICATE | Conversation message client id reused outside its original conversation | - |
MESSAGE_TOO_LONG | Conversation message content over the allowed length | Your message is too long. Please shorten it to %{limit} characters or fewer and try again. |
GUEST_SUPPORT_ACTIVE | Guest support: an open guest thread already exists for this contact (#869) - the guest is told to continue via the link emailed to them, not to start another. | - |
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. |
MESSAGE_REQUEST_NOT_FOUND | Action attempted on a thread the user does not participate in | - |
RECEIPT_NOT_SHAREABLE | Receipt sharing attempted for a transaction that is not successful | This payment hasn't completed, so a receipt can't be shared yet. Once it shows as successful in your history, you can share its receipt. |
INVALID_EMAIL | Invalid email format | - |
INVALID_PHONE | Invalid phone number format | That doesn't look like a valid phone number. Please check it and try again. |
INVALID_AMOUNT | Invalid amount value | - |
INVALID_CATEGORY | Invalid category parameter | Please select a valid transaction type (purchase or funding). |
EMAIL_EXISTS | Duplicate email registration | - |
PHONE_EXISTS | Duplicate phone registration | - |
SAME_EMAIL | Email change to same email | - |
DUPLICATE_REFERENCE | Duplicate transaction reference | - |
Resource Not Found Errors (HTTP 404)
| Code | Description | User-facing message |
|---|---|---|
NOT_FOUND | Generic not found | - |
USER_NOT_FOUND | User doesn't exist | We couldn't find an account with this email address. Please check your email or create a new account. |
ACCOUNT_NOT_FOUND | Account doesn't exist | We couldn't find an account for your profile. Please contact support. |
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. |
DEVICE_NOT_FOUND | Device not in database | - |
SCHEDULE_NOT_FOUND | Schedule doesn't exist | - |
EVENT_NOT_FOUND | Event doesn't exist | - |
COMMISSION_NOT_FOUND | Commission doesn't exist | - |
CONVERSATION_NOT_FOUND | Conversation doesn't exist | We couldn't find that conversation. It may have been removed. |
BENEFICIARY_NOT_FOUND | Beneficiary doesn't exist (or not owned by the current account) | We couldn't find that saved contact. It may have already been removed. |
SESSION_NOT_FOUND | Session doesn't exist | - |
PASSKEY_NOT_FOUND | Passkey doesn't exist | - |
Session & Verification Errors (HTTP 400/401)
| Code | Description | User-facing message |
|---|---|---|
SESSION_EXPIRED | Session past TTL | Your session has expired. Please sign in again. |
MAGIC_LINK_INVALID | Magic link not found or used | This sign-in link is invalid or has expired. Please request a new one. |
MAGIC_LINK_EXPIRED | Magic link past expiration | - |
MAGIC_LINK_USED | Magic link already used | - |
VERIFICATION_CODE_INVALID | Wrong verification code entered | - |
VERIFICATION_CODE_EXPIRED | Verification code past expiration | - |
TOO_MANY_ATTEMPTS | Max verification attempts exceeded | - |
KYC_TIER_REQUIRED | Sender has not completed the KYC tier required to move money | - |
TRANSACTION_CODE_REQUIRED | Sender must set a transaction code before moving money | Please set up your transaction code before sending money. It keeps your transfers secure, and no money has left your account. |
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. |
LOGIN_RATE_LIMITED | Too many login attempts | For your security, we've paused sign-in attempts. Please wait a few minutes and try again. |
REGISTRATION_RATE_LIMITED | Too many registrations from IP | - |
PASSWORD_RESET_RATE_LIMITED | Too many password reset requests | - |
EMAIL_CHANGE_RATE_LIMITED | Too many email change requests | - |
VERIFICATION_RATE_LIMITED | Too many verification code requests | - |
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. |
OVERAGE_DISABLED | Overage billing is disabled on subscription | - |
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 | - |
RECIPIENT_NOT_FOUND | Transfer recipient could not be resolved | - |
TRANSFER_TO_SELF | Transfer where sender and recipient are the same account | You can't send money to yourself. Please choose a different recipient. |
INVALID_TRANSACTION_TYPE | Invalid transaction type | - |
VIRTUAL_ACCOUNT_EXISTS | Duplicate virtual account request | You already have a virtual account. Please use your existing account for bank transfers. |
DISPUTE_UNAUTHORIZED | User not authorized to dispute | You cannot dispute this transaction. |
DISPUTE_NOT_ALLOWED | Transaction not eligible for dispute | This transaction can't be disputed. If you think this is a mistake, please contact support. |
DISPUTE_FAILED | Dispute creation error | We couldn't create your dispute. Please try again later. |
INVALID_STATUS | Wrong transaction status for action | - |
Scheduled Transaction Errors (HTTP 400)
| Code | Description | User-facing message |
|---|---|---|
SCHEDULE_CREATE_FAILED | Schedule validation/creation failed | - |
SCHEDULE_UPDATE_FAILED | Schedule update failed | - |
SCHEDULE_CANCEL_FAILED | Schedule cancel failed | - |
SCHEDULE_PAUSE_FAILED | Schedule not pausable | - |
SCHEDULE_RESUME_FAILED | Schedule not resumable | - |
SUGGESTION_ALREADY_PROCESSED | Suggested schedule already actioned | - |
Device & Security Errors (HTTP 400/401)
| Code | Description | User-facing message |
|---|---|---|
DEVICE_NOT_REGISTERED | Device not registered | We don't recognise this device. Please sign in again on a registered device. |
DEVICE_IDENTIFICATION_REQUIRED | Missing device fingerprint in request | - |
ATTESTATION_FAILED | App integrity attestation failed | - |
CHALLENGE_EXPIRED | Attestation challenge token expired | - |
CANNOT_LOGOUT_CURRENT | Attempted logout of current device | - |
CANNOT_REVOKE_CURRENT | Attempted revocation of current device | - |
TRANSACTION_CODE_INVALID | Transaction code validation failed | That transaction code is incorrect. Please try again. |
TRANSACTION_CODE_LOCKED | Transaction code locked after failures | For your security, your transaction code is locked. Please use Forgot Code to reset it. |
Registration Errors (HTTP 400)
| Code | Description | User-facing message |
|---|---|---|
REGISTRATION_FAILED | General registration failure | We couldn't complete this step of your registration. Please check your details and try again. |
EMAIL_NOT_SUPPORTED | Disposable / unsupported email rejected at signup | We couldn't send your message with that email. Please use a permanent inbox like Gmail or Outlook so our team can reply to you. |
ACCOUNT_EXISTS | Contact already belongs to a registered account (incl. | - |
REGISTRATION_SESSION_EXPIRED | Registration session TTL exceeded | - |
EMAIL_NOT_VERIFIED | Email verification required | - |
DETAILS_NOT_COMPLETED | Personal details step required | - |
AUTH_METHOD_REQUIRED | Auth method setup required | - |
KYC_ALREADY_COMPLETED | KYC upgrade already completed | - |
PASSKEY_SETUP_FAILED | WebAuthn registration failed | - |
PASSKEY_OPTIONS_FAILED | WebAuthn challenge generation failed | We couldn't set up your passkey right now. Please try again in a moment. |
INVALID_REGISTRATION_STEP | Attempting to access a registration step out of order | - |
File Upload Errors (HTTP 400)
| Code | Description | User-facing message |
|---|---|---|
NO_FILE_ATTACHED | No file in request body | - |
FILE_ATTACH_FAILED | Upload processing fails | - |
WhatsApp Errors (HTTP 400/401)
| Code | Description | User-facing message |
|---|---|---|
WHATSAPP_TOKEN_INVALID | Invalid WhatsApp session token | - |
WHATSAPP_TOKEN_EXPIRED | WhatsApp token past expiration | - |
WHATSAPP_USER_MISMATCH | Wrong passkey for WhatsApp session | - |
WHATSAPP_LOGIN_FAILED | General WhatsApp auth failure | - |
WHATSAPP_SIGNATURE_MISSING | Missing webhook signature header | - |
WHATSAPP_SIGNATURE_INVALID | Invalid webhook signature | - |
NO_WHATSAPP_SESSION | No WhatsApp session exists | - |
NO_PHONE_NUMBER | User has no phone number | - |
AI Feature Errors (HTTP 400/403)
| Code | Description | User-facing message |
|---|---|---|
AI_MESSAGE_BLANK | Empty AI message content | - |
AI_ACCESS_DENIED | User not AI-enabled | - |
AI_SCORE_REQUIRED | Earn AI score gate: resume / cover letter generation requires a recent AI score | Run AI score first - it is required before generating documents. |
PROFILE_INCOMPLETE | Earn profile gate: profile is too thin to run AI scoring or document generation | Add basic profile info (name, a target role or summary, and at least one work experience) to use AI features. |
RATE_LIMITED | Earn targeted AI rewrite: upstream LLM rate-limited the request | You've sent us a few messages already. Please wait a little while before sending another. |
LLM_UNAVAILABLE | Earn targeted AI rewrite: upstream LLM is degraded or unreachable | AI rewrite service is temporarily unavailable. Please try again in a moment. |
LLM_CONTEXT_TOO_LONG | Earn targeted AI rewrite: input would exceed the model's context window | That text is too long to rewrite. Try shortening it and try again. |
LLM_RESPONSE_INVALID | Earn targeted AI rewrite: LLM responded but the payload failed schema validation | AI rewrite returned an unexpected response. Please try again. |
UNSAFE_INPUT | Earn targeted AI rewrite: input failed pre-LLM safety / length / shape check | - |
Password/Passcode Errors (HTTP 400)
| Code | Description | User-facing message |
|---|---|---|
PASSWORD_UPDATE_FAILED | Password change fails | - |
PASSCODE_UPDATE_FAILED | Passcode change fails | - |
PASSKEY_UPDATE_FAILED | Passkey nickname change fails | - |
PASSKEY_DELETE_FAILED | Passkey removal fails | - |
EMAIL_SEND_FAILED | Email sending fails | - |
Two-Factor Authentication Errors (HTTP 400/422)
| Code | Description | User-facing message |
|---|---|---|
TWO_FACTOR_INVALID_CODE | Invalid TOTP/backup code | The verification code you entered is incorrect. Please try again. |
TWO_FACTOR_METHOD_NOT_AVAILABLE | 2FA method not available (disabled in config) | This 2FA method is not currently available. |
TWO_FACTOR_ALREADY_ENABLED | Method already enabled | This 2FA method is already enabled on your account. |
TWO_FACTOR_NO_SETUP | No setup in progress | No authenticator setup in progress. Please start the setup process first. |
TWO_FACTOR_EMAIL_NOT_VERIFIED | Email not verified (required for email 2FA) | Please verify your email address before enabling email 2FA. |
TWO_FACTOR_NO_PASSKEYS | No passkeys registered (required for passkey 2FA) | You need to register at least one passkey before enabling passkey 2FA. |
TWO_FACTOR_CANNOT_DISABLE_LAST | Cannot disable last method | You cannot disable your last 2FA method. Please set up another method first. |
TWO_FACTOR_EMAIL_CANNOT_BE_DEFAULT | Email cannot be default method | Email cannot be set as your default 2FA method. Please choose authenticator or passkey. |
TWO_FACTOR_METHOD_NOT_FOUND | Method not found | This 2FA method is not enabled on your account. |
TWO_FACTOR_REQUIRES_PRIMARY_METHOD | Requires another method first (e.g., email needs authenticator/passkey) | Please set up authenticator or passkey before enabling email 2FA. |
TWO_FACTOR_INVALID_SETTING | Invalid login requirement setting | Please select a valid 2FA requirement setting. |
TWO_FACTOR_REQUIRED | Cannot disable 2FA (required for admin users) | Two-factor authentication is required for your account and cannot be disabled. |
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. |
Partner Consumer Platform
| Code | Description | User-facing message |
|---|---|---|
CONSUMER_SUBDOMAIN_NOT_FOUND | - | We couldn't find this store. Please check the link and try again. |
CONSUMER_SUBDOMAIN_INACTIVE | - | This storefront is not available. |
CONSUMER_INVALID_TOKEN | - | Invalid or expired token. Please log in again. |
CONSUMER_TOKEN_EXPIRED | - | Your session has expired. Please log in again. |
CONSUMER_TOKEN_SUBDOMAIN_MISMATCH | - | Invalid or expired token. Please log in again. |
CONSUMER_INVALID_PAYLOAD | - | We couldn't process this request. Please check your details and try again. |
Next Steps
- Error Handling - Partner API response format and handling patterns
- Sandbox Testing - Trigger errors safely while testing
- Rate Limiting - Understand 429 responses