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 CodeDescriptionNext Step
2XXSuccessful API request.
4XXFailed API Request.

This is because of the error in the information provided by you.

Example:
  • Bad request
  • Invalid path
  • Invalid method
When these error messages are returned check and correct the information passed in the API request.
5XXFailed API request.

This is returned when:
  • Plural server return errors.
  • Plural service provider's system error.
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.

ParameterTypeDescription
codestringShort code for the error returned.

Possible values:
  • INVALID_REQUEST
  • PAYMENT_RATE_LIMIT
  • CARD_EXPIRED
  • RISK_CHECK_FAILED
  • INTERNAL_ERROR
messagestringCorresponding 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 CodeError CodeError CategoryError Description
500INTERNAL_ERRORsystemInternal server error. The request cannot be processed at this time.
400INVALID_REQUESTrequestThe request does not the expected contract and cannot be processed. This may be due to malformed request, invalid or missing parameters.
422UNAUTHORIZEDrequestThe client is not authorized to perform this operation.
422DUPLICATE_REQUESTrequestThe request has already been processed.
422API_RATE_LIMITrequestThe request was rejected because the client has sent too many requests in a given time window.
422PAYMENT_METHOD_NOT_ENABLEDvalidationThe specified payment method is not enabled for the merchant.
422OPERATION_NOT_ALLOWEDvalidationThe specified operation cannot be made because required precondition has failed.
404ORDER_NOT_FOUNDvalidationNo order with specified order-id exists in the system.
422ORDER_CANCELLEDvalidationThe order has already been cancelled and cannot be modified further.
422PAYMENT_NOT_AUTHORIZEDpayment errorThe payment requires authorization before it can be processed.
422PAYMENT_PENDINGpayment errorThe payment is pending and requires authorization before it can be processed.
422PAYMENT_EXPIREDpayment errorThe payment has expired and cannot be modified further.
422PAYMENT_DECLINEDpayment errorThe payment was declined by the acquirer.
422PAYMENT_RATE_LIMITpayment errorThe payment was declined because too many payments were attempted using the specified payment option.
422INVALID_INSTRUMENTinstrumentThe payment instrument details are not valid.
422RISK_CHECK_FAILEDinstrumentThe payment was declined after a risk check.
422ISSUER_NOT_SUPPORTEDinstrumentThe specified issuer is not supported for this operation.
422INSUFFICIENT_FUNDSinstrumentInsufficient funds to proceed with payment using the specified payment option.
422AMOUNT_LIMIT_EXCEEDEDinstrumentThe transaction was declined because the specified amount exceeds allowed limits.
422INVALID_CARDHOLDERcardInvalid card holder specified on the card payment option.
422CARD_VERIFICATION_FAILEDcardInvalid CVV specified on the card payment option.
422CARD_NOT_ALLOWEDcardSpecified card is not allowed for this transaction.
422CARD_STOLENcardSpecified card is not allowed for this transaction because it was flagged as stolen.
422CARD_LOSTcardSpecified card is not allowed for this transaction because it was flagged as lost.
422CARD_EXPIREDcardSpecified card is not allowed for this transaction because it has expired.
422CARD_NOT_ENROLLEDcardSpecified 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.