Error Handling Overview

These error codes may be returned when making API calls through any BlueSnap API, including our Payment API, Reporting API, and Embedded Payments API. If the API request and response are successful, the Payment API will return one of the following HTTP status codes:

200: when a new resource is created and returned in the body of the response
201: when a new resource is created and the URL to it is returned in the header (typically as a “Location" parameter)
204: when an update resource is successful, but nothing is returned in the body or header

Otherwise, the API returns one of the following error types:

HTTP 500 errors

If an unexpected error occurs in the BlueSnap system, the API will send an error with HTTP 500 status code. Please contact BlueSnap Merchant Support, if you need further assistance or information regarding an HTTP 500 error.

HTTP 503 and 429 errors

These HTTP error codes are returned when a merchant exceeds the authorized thresholds for API calls to the BlueSnap system, or if a specific service has reached its maximum allowed limits of calls. One of the messages below is also returned to further indicate the specific threshold reached:

Client request rate is too high
Client request concurrency is too high
Request rate for service is too high
Request concurrency to specific service is too high
Service is temporarily unavailable

HTTP 422 error

The server understands the content type of the request entity and the syntax of the request entity is correct. However, it was unable to process the contained instructions. Your request is well-formed and syntactically correct, but semantically incorrect.

HTTP 409 error

This indicates a request conflict with the current state of the target resource. It's possible that the error is related to idempotency; there may be an identical request with the same Idempotency-Key already in progress.

HTTP 403 error

When an API user does not have the required role (authorization) to perform a specific operation, the API returns an error with HTTP 403 status code. API user roles depend on your SAQ level, as described in PCI compliance. HTTP 403 is also returned if a merchant tries to access a resource (shopper, transaction, or other) that does not exist, or if the API call has been blocked by BlueSnap’s security defenses for suspected malicious content.

HTTP 404 error

When the server cannot find the requested resource, it returns a 404 error. This indicates that the resource does not exist or was not correctly included in the request. For example, if a merchant tries to perform a Get Vaulted Shopper request using the merchant shopper ID and the shopper cannot be found, the system will return a 404 error.

HTTP 400 errors

If the request contains invalid data or the acquirer/processor has an issue with processing the transaction, the API will send an error with HTTP 400 status code, and an error message in JSON format in the body of the response. In most cases, these errors are formatted as follows:

{
  "message": [
  {
    "errorName": "ERROR_NAME",
    "code": BLUESNAP ERROR CODE,
    "description": "GENERAL DESCRIPTION OF THE ERROR"
  },
  {
    "errorName": "ERROR_NAME2",
    "code": BLUESNAP ERROR CODE 2,
    "description": "GENERAL DESCRIPTION OF THE ERROR 2",
    
    "invalidProperty": {
      "name": "{PROPERTY THAT FAILED VALIDATION}"
    }
  }
 ]
}

All Error Lists

For reference, see the following error lists: