Error codes

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.

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.

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.

{
  "code":"UNAUTHORIZED",
  "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.

📘

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.