Handling Errors

Overview

When sending a request to the Acquired.com API you will always receive a response in JSON format. Within the response you will also receive a HTTP status code, confirming whether the request was successful or not. If the request was not successful, you can tell by the status, error_type and title and work out how to resolve the issue.

Attributes

Field	Type	Description	Example
`status`	string	The status of the response.	`error`
`error_type`	string	The type of error returned.	`bad_request` `unauthorized` `forbidden` `conflict` `internal_server_error` `configuration`
`title`	string	A human-readable message that provides more detail about the error.	'Authentication with the API failed, please check your details and try again.'
`instance`	string	Indicates where the error occurred.	/v1/login
`invalid_parameters`	object	The object detailing the parameters the error occurred in and the reason.
`parameter`	string	Details the parameters where the error has occurred.	`payment.card.scheme`
`reason`	string	Gives detail as to what is causing the error within the parameters.	'Scheme and number values do not match.'

Examples of error responses

See below a few examples of errors that you can encounter.

401 - Unauthorized

The below request includes an invalid app_key:

{
  "app_id": "app_id",
  "app_key": "deliberately_incorrect_app_key"
}

Response:

{
  "status": "error",
  "error_type": "unauthorized",
  "title": "Authentication with the API failed, please check your details and try again.",
  "instance": "/v1/login"
}

409 - Conflict

In the next request we are trying to create a new customer record:

{
	"reference": "customer_number_00001",
	"first_name": "Edward",
	"last_name": "Johnson",
	"dob": "1988-10-03",
	"billing": {
		"address": {
			"line_1": "152 Aldgate Street",
			"line_2": "",
			"city": "London",
			"state": "",
			"postcode": "E1 7RT",
			"country_code": "GB"
		}
	}
}

Response:

{
  "status": "error",
  "error_type": "conflict",
  "title": "There was a conflict when trying to complete your request",
  "instance": "/v1/customers",
  "invalid_parameters": [
  {
  "parameter": "reference",
  "reason": "A customer already exists using reference customer_number_00001"
  }
  ]
}

400 - Bad Request

We will also report on multiple syntax errors, rather than sending one validation error at a time.

In the below request there are syntax errors in the following parameters: transaction.currency, payment.card.scheme, payment.card.number and payment.card.cvv.

Request:

{
   "transaction": {
       "order_id": "{{$guid}}",
       "amount": 20.99,
       "currency": "Gbpg",
       "moto": false,
       "capture": true
   },
   "payment": {
       "card_id": "",
       "card": {
           "holder_name": "E Smith",
           "scheme": "vis",
           "number": "400001118013871",
           "expiry_month": 10,
           "expiry_year": 26,
           "cvv": "12"
       },
       "create_card": true,
       "reference": "Custom Ref 001"
   },
  "customer": {
      "customer_id": "4f3970f9-3cf8-424d-299e-631dea1b7d30"
  },
   "tds": {
       "is_active": false,
       "challenge_preference": "no_preference",
       "challenge_window_size": "full_screen",
       "contact_url": "https://yourdomain.com/contact",
       "redirect_url": "https://qaacs.acquired.com/merchant_redirect/test_success",
       "webhook_url": ""
   }
}

Response:

{
    "status": "error",
    "error_type": "validation",
    "title": "Your request parameters did not pass our validation.",
    "instance": "/v1/payments",
    "invalid_parameters": [
        {
            "parameter": "transaction.currency",
            "reason": "format is invalid, must be [aed,aud,acd,chf,cny,dkk,eur,gbp,hkd,jpy,mxn,sek,usd,zar]"
        },
        {
            "parameter": "payment.card.scheme",
            "reason": "payment.card.scheme must be string and in visa,mastercard,amex"
        },
        {
            "parameter": "payment.card.number",
            "reason": "payment.card.number validation failed"
        },
        {
            "parameter": "payment.card.cvv",
            "reason": "payment.card.cvv validation failed"
        }
    ]
}

Error Logs

We will display a log of all API errors within the Acquired.com Hub. The full error request log will be displayed, including the initial request and the full response data.

Firstly, go to Settings > Developers.
Navigate to the Error Log tab and locate the required error. (Use the filters and export, as per existing functionality within the Hub.)
See the full error log detail by clicking on the ellipsis and selecting View Details.