Error Code Registry

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: 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.

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 - Developer API response format and handling patterns
• Sandbox Testing - Trigger errors safely while testing
• Rate Limiting - Understand 429 responses