--- title: Error Code Registry description: Every RizPay platform error code, generated from the backend source of truth --- {/* GENERATED FILE - DO NOT EDIT BY HAND. */} {/* Regenerate with: yarn docs:errors (from landing/). */} {/* Source: backend/app/controllers/concerns/error_codes.rb and backend/config/locales/en.yml */} > **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:errors` from 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](/developers/docs/getting-started/errors). For the Partner API response format and the error codes you are most likely to encounter when integrating, start with [Error Handling](/developers/docs/getting-started/errors). 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](/developers/docs/getting-started/errors) - Partner API response format and handling patterns - [Sandbox Testing](/developers/docs/core-concepts/sandbox) - Trigger errors safely while testing - [Rate Limiting](/developers/docs/core-concepts/rate-limiting) - Understand 429 responses