Errors
Plutu provides a list of error codes and messages for troubleshooting payment integration issues.
Plutu uses HTTP response status codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with Plutu's servers (these are rare).
Some 4xx errors that could be handled programmatically (e.g., an invalid gateway) include an error code—a short string with a brief explanation—as a value for code. Below is a list of possible error codes that can be returned.
200
401 -403 -404 -422 -429
500- 502 -503 - 504 - Server Error
| Status | Description |
|---|---|
200 - OK | indicates that the request has succeeded, and everything works as expected. |
400 - Bad Request | indicates that the server cannot or will not process the request. |
401 - Unauthorized | indicates that the client request has not been completed because it lacks valid authentication credentials for the requested resource. An invalid access token/API key was provided. |
403 - Forbidden | indicates that the server understands the request but refuses to authorize it. API key doesn't have permission to perform the request. |
404 - Not Found | The requested resource doesn't exist. |
422 - Un-processable Entity | Invalid fields will result in a 422 Unprocessable Entity response. |
429 - Too Many Requests | indicates the user has sent too many requests in a given amount of time. |
500, 502, 503, 504 - Server Errors | Something went wrong on Plutu's end. (These are rare). |
REVIEWING ERRORS
To monitor your integration and review errors, Plutu logs every API request your integration makes, whether it was successful or failed. You can access the logs section of the Dashboard under Gateways to review these errors.
General Errors
General errors are a type of error that can occur when using a payment gateway integration. They are not specific to any particular endpoint or gateway and can be caused by a variety of issues such as incorrect input data, network connectivity problems, or errors with the integration itself. It's important to review these errors and understand their root cause in order to address them and ensure the smooth functioning of your payment gateway integration.
MAINTENANCE_MODE
Plutu maintenance mode is enabled
UNAUTHORIZED
Invalid access token/API key provided, or your account has not been approved yet
DENIED_ACCESS_GATEWAY
Access denied, you do not have permission to access the payment method
MISSING_PARAMETER
Due to the missing payment gateway configuration
INVALID_INPUTS
Payment fields are incorrectly filled out
BACKEND_ERROR
Plutu Backend error
FORBIDDEN_IP_ADDRESS
The IP address is not whitelisted
TEST_MODE_NOT_SUPPORTED
Test mode is not supported for payment gateway
TOO_MAY_REQUESTS
Too many requests received
INVALID_AMOUNT_FORMAT
Transaction amount format is invalid, format is allowed with a maximum of two decimal places: XXX, XX.X, XX.XX
AMOUNT_NOT_ALLOWED
Amount must be greater than zero
AMOUNT_EXCEEDED_MAXIMUM
Amount exceeded the maximum amount allowed for a transaction: 50000 per transaction. For sandbox: maximum 500 per transaction
CURRENCY_NOT_SUPPORTED
Currency is not supported
SANDBOX_TRANSACTION_LIMIT_EXCEEDED
Reaching the maximum number of transactions allowed during the period specified in the sandbox environment
Sadad Errors
The following errors, as well as General Errors, can be returned.
INVALID_AMOUNT
Invalid amount
INVALID_PROCESS_ID
The process ID is invalid or does not match the value received in the (verify) request (lifetime 10 minutes)
INVALID_MOBILE_NUMBER
Incorrect mobile number
INVALID_MOBILE_NUMBER_OR_BIRTH_YEAR
Incorrect mobile number/year of birth
INVLIAD_OTP
Invalid OTP. please check your code and try again
INVALID_INVOICE_AMOUNT_OR_NUMBER
Invoice number already exists
EMPTY_MOBILE_NUMBER
The mobile number is empty
EMPTY_BIRTH_YEAR
Birth year is empty
OTP_EXPIRED
The OTP has exceeded the time allowed for its use
OTP_WAIT_BEFORE_RESNED
Please wait a while before requesting an OTP resend again
INVALID_MERCHANT_CATEGORY
Merchant category configuration is missing
UNAUTHORIZED_MERCHANT_ACCOUNT
Unauthorized merchant account
NOT_ALLOWED_AMOUNT
Transaction amount is not allowed
INSUFFICIENT_BALANCE
Insufficient balance for the transaction
PHONE_NUMBER_IS_LOCKED
Phone number is locked
EXCEED_MONTHLY_AMOUNT
The customer has exceeded the allowed monthly amount
SERVICE_NOT_AVAILABLE
Sadad payment service is not available, Please contact Sadad to ensure that the service is activated
ALLOWED_ATTEMPTS_EXCEEDED
You have exceeded the number of allowed transaction attempts
INVALID_CREDENTIALS
Invalid Sadad credentials
UNKNOWN
Unknown error, related to the service provider
Adfali Errors
The following errors, as well as General Errors, can be returned.
NOT_SUBSCRIBED
The mobile number is not subscribed to Adfali service
INVALID_AMOUNT
Invalid amount
INVALID_PROCESS_ID
The process ID is invalid or does not match the value received in the (verify) request (lifetime 10 minutes)
CONFIRMATION_ERROR
Payment confirmation error, check OTP code
INVALID_MOBILE_NUMBER
Incorrect mobile number
CHECK_BANK_ACCOUNT
There is a problem with your account, please check with your bank account
ADD_PAYMENT_ERROR
payment error, unable to reach server or problem connecting to server
BACKEND_SERVER_ERROR
There is a problem connecting to the bank server, please try again later
AUTH_ERROR
Unable to reach the Adfali server right now
INVALID_CREDENTIALS
Invalid Adfali credentials
Local Bank Cards
There are no errors for Local Bank Cards, Only the General Errors can be returned
Lightbox Errors
On the checkout page (Lightbox), service providers may return error messages that are not specific to Plutu API. Here is an explanation for those error messages.
Order Not Found!
General error but the credentials may be incorrect for use in a production environment
Invalid Domain Request !
The domain URL associated with your account by the bank is incorrect. The URL must be https://api.plutus.ly
Merchant or terminal is currently inactive
Your account has not been activated or has been suspended by the bank or service provider
T-Lync Errors
There are no errors for T-Lync, Only the General Errors can be returned
MPGS Errors
The following errors, as well as General Errors, can be returned.
CURRENCY_NOT_SUPPORTED
Transaction currency is not supported by the merchant account.
You need to check your MPGS account that supports the selected currency
INACTIVE_API
MPGS account is not enabled for purchase. You need to contact your service provider to enable the 'PURCHASE' operation
Last updated