Error responses

Applies to both APIs.

The two return different error shapes, and an integration that spans both has to handle both.

A connector wraps all of this in its own message, so what you see on the Integration Orders page is a reason string, not an HTTP error. That page is the right one.

Credentials, order states and webhooks are shared. Error shapes are not: the two APIs use completely different envelopes.

If you call both, write two error handlers. Branch on the host, not on trying to parse one shape and falling back to the other.

status and code carry the error code, message carries a sentence, and details.type says what kind of failure it was.

{
  "status": "invalid_argument",
  "code": "invalid_argument",
  "message": "Invalid Input",
  "details": {
    "type": "input",
    "fields": [
      { "field": "name", "message": "required" },
      { "field": "email", "message": "email" },
      { "field": "address.street", "message": "required" }
    ]
  }
}

details.fields names the field that failed, using dotted paths for nested objects. Read it and show it to the user. This is the part last-mile does not have.

The list is not exhaustive and more codes are added over time. Branch on the HTTP status and treat an unrecognised code as its status class.

Which shape you get depends on the endpoint and on how early the request was rejected.

{ "api_error": {
    "id": 1002,
    "code": "Error Code",
    "message": "Error Message",
    "human": "Human readable error message",
    "description": "Detailed human readable error description",
    "http_status_code": 400,
    "attribute_errors": [ { "detail": "additional error code" } ]
} }

{ "error": "invalid_client" }

{ "error": "unauthorized" }

{ "result": 103, "level": "error", "message": "00001 is an invalid postcode" }

The last shape above, { "result", "level", "message" }, does not come from any /orders endpoint. It exists elsewhere on the platform, so handle it defensively if you meet it.

Three things about the api_error shape will catch you out.

api_error.http_status_code does not always match the HTTP status. A create with an invalid items array comes back as HTTP 400 carrying http_status_code: 422. Trust the HTTP status.

api_error.message and error are sometimes empty strings. An invalid payment_mode, and an invalid kind, both return 422 with every message field blank. There is nothing in the response telling you which field was wrong.

attribute_errors comes back as an array of {detail}. Some older Quiqup material shows it as a bare object. The array is what the API sends.

The five fields are not independent. error, errors[0].detail, error_details[0].detail and api_error.message all carry the same string, and error_detail repeats api_error.human.

One string covers several unrelated commercial restrictions. None of them are payload bugs, so debugging your request will not help.

Both APIs. Malformed payloads can surface as 500 rather than 422 on the last-mile POST /orders and PUT /orders/{order_id}/ready_for_collection. Validate your payload shape before assuming an outage.

If it persists, send the exact request, the exact response and the UTC timestamp to apisupport@quiqup.com.