Error Codes
Learn about the HTTP error responses returned from Plural APIs.
Plural aims to process all the API requests successfully to provide the optimal user experience. Each API request can either return a successful response or a failed response. Successful API responses are indicated by an HTTP status code in the 2XX range. Any status code outside of the 2XX range signifies a failed request. Common reasons for API call failures include human input errors, network issues, and intermittent connectivity problems.
The error response helps to:
- Identify and examine the causes of failure.
- Identifying measures to resolve the unsuccessful response.
The table below lists the various HTTP response codes we return to indicate successful or failed API calls.
HTTP Status Code | Description | Next Step |
---|---|---|
2XX | Successful API request. | |
4XX | Failed API Request. This is because of the error in the information provided by you. Example:
| When these error messages are returned check and correct the information passed in the API request. |
5XX | Failed API request. This is returned when:
| Try after some time. |
Error Structure
The error response contains the code
and message
parameters in the error response. These parameters helps to identify reasons for the error.
The table below gives a brief description of the various parameters returned in the error message with all non-2XX HTTP status codes.
Parameter | Type | Description |
---|---|---|
code | string | Short code for the error returned. Possible values:
|
message | string | Corresponding error message for the code. Example: Amount must be an Integer value greater than or equal to 1 |
Shown below are the sample error response for 400 HTTP status code.
{
"code": "INVALID_REQUEST",
"message": "Amount must be an Integer value greater than or equal to 1"
}
{
"code": "INVALID_REQUEST",
"message": "Amount must be an Integer value less than or equal to 100000000"
}
{
"code": "INVALID_REQUEST",
"message": "Merchant Order Reference must not be empty"
}
{
"code": "INVALID_REQUEST",
"message": "Merchant Order Reference must be less than or equal to 50 characters"
}
{
"code": "INVALID_REQUEST",
"message": "Payment method is missing/invalid"
}
Shown below are the sample error response for 401 HTTP status code.
{
"message": "Unauthorized"
}
Shown below are the sample error response for 422 HTTP status code.
{
"code": "PAYMENT_RATE_LIMIT",
"message": "Failure due to request velocity or limit checks"
}
{
"code": "CARD_EXPIRED",
"message": "Payment Instrument has expired"
}
{
"code": "RISK_CHECK_FAILED",
"message": "Payment Instrument suspected to be used fraudulently"
}
Shown below are the sample error response for 500 HTTP status code.
{
"code": "INTERNAL_ERROR",
"message": "Internal Server Error"
}
{
"code": "INTERNAL_ERROR",
"message": "Payment processor is unavailable"
}
Common Error Codes
The below table lists all the possible error codes returned in our API responses.
Status Code | Error Code | Error Category | Error Description |
---|---|---|---|
500 | INTERNAL_ERROR | system | Internal server error. The request cannot be processed at this time. |
400 | INVALID_REQUEST | request | The request does not the expected contract and cannot be processed. This may be due to malformed request, invalid or missing parameters. |
422 | UNAUTHORIZED | request | The client is not authorized to perform this operation. |
422 | DUPLICATE_REQUEST | request | The request has already been processed. |
422 | API_RATE_LIMIT | request | The request was rejected because the client has sent too many requests in a given time window. |
422 | PAYMENT_METHOD_NOT_ENABLED | validation | The specified payment method is not enabled for the merchant. |
422 | OPERATION_NOT_ALLOWED | validation | The specified operation cannot be made because required precondition has failed. |
404 | ORDER_NOT_FOUND | validation | No order with specified order-id exists in the system. |
422 | ORDER_CANCELLED | validation | The order has already been cancelled and cannot be modified further. |
422 | PAYMENT_NOT_AUTHORIZED | payment error | The payment requires authorization before it can be processed. |
422 | PAYMENT_PENDING | payment error | The payment is pending and requires authorization before it can be processed. |
422 | PAYMENT_EXPIRED | payment error | The payment has expired and cannot be modified further. |
422 | PAYMENT_DECLINED | payment error | The payment was declined by the acquirer. |
422 | PAYMENT_RATE_LIMIT | payment error | The payment was declined because too many payments were attempted using the specified payment option. |
422 | INVALID_INSTRUMENT | instrument | The payment instrument details are not valid. |
422 | RISK_CHECK_FAILED | instrument | The payment was declined after a risk check. |
422 | ISSUER_NOT_SUPPORTED | instrument | The specified issuer is not supported for this operation. |
422 | INSUFFICIENT_FUNDS | instrument | Insufficient funds to proceed with payment using the specified payment option. |
422 | AMOUNT_LIMIT_EXCEEDED | instrument | The transaction was declined because the specified amount exceeds allowed limits. |
422 | INVALID_CARDHOLDER | card | Invalid card holder specified on the card payment option. |
422 | CARD_VERIFICATION_FAILED | card | Invalid CVV specified on the card payment option. |
422 | CARD_NOT_ALLOWED | card | Specified card is not allowed for this transaction. |
422 | CARD_STOLEN | card | Specified card is not allowed for this transaction because it was flagged as stolen. |
422 | CARD_LOST | card | Specified card is not allowed for this transaction because it was flagged as lost. |
422 | CARD_EXPIRED | card | Specified card is not allowed for this transaction because it has expired. |
422 | CARD_NOT_ENROLLED | card | Specified card is not allowed for this transaction because it is not enrolled for 3DS |
Note:
- For the unstructured error returned from Plural, the response may not always include a corresponding code and message. In such cases, refer to the HTTP status codes to determine the status of the API request.
Updated 7 days ago