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

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.

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

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.

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

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.

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"
  }
}