Payment API Error Codes – Pine Labs Developer Guide

Pine Labs Online 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: `Bad request` `Invalid path` `Invalid method`	When these error messages are returned check and correct the information passed in the API request.
5XX	Failed API request. This is returned when: Pine Labs Online server return errors. Pine Labs Online 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.

Parameter	Type	Description
code	`string`	Short code for the error returned. Possible values: `INVALID_REQUEST` `PAYMENT_RATE_LIMIT` `CARD_EXPIRED` `AMOUNT_LIMIT_EXCEEDED` `INTERNAL_ERROR`
message	`string`	Corresponding error message for the code. Example: `The transaction was declined because the specified amount exceeds allowed limits`
additional_error_details [Optional]	`object`	An object that contains the `additional_error_details` object. Learn more about our `additional_error_details` object.

Additional Error Details [Child Object]

The table below lists the various parameters in the additional_error_details child object. This object is part of the http_error response object.

Parameter	Type	Description
source	`string`	Indicates where the error originated. Example: `ACQUIRER`
step	`string`	Specifies the stage in which the error occurred. Example: `payment_eligibility_check`
reason	`string`	Describes the cause of the error, explaining why and where it has occurred. For example, The field value is `transaction_limit_exceeded` is passed.

Shown below is a sample error response for an HTTP 422 status code.

{
  "code": "AMOUNT_LIMIT_EXCEEDED",
  "message": "The transaction was declined because the specified amount exceeds allowed limits",
  "additional_error_details": {
    "source": "ACQUIRER",
    "step": "payment_eligibility_check",
    "reason": "transaction_limit_exceeded"
  }
}