Response codes (v1) · GXBiQ API docs

Process shipments reports failures as RFC 7807 problem documents. This table lists every status code it can return.

Code	When	Body
`200 OK`	The batch was processed.	An array of shipment results, one per requested shipment, in the same order. Check `customResponse.hasError` on each shipment and each parcel.
`400 Bad Request`	A missing, malformed or repeated `Idempotency-Key`; the key reused with a different body; an empty array; more than 100 shipments; or a field that fails validation.	A problem document. Field validation failures list the fields under `errors`.
`401 Unauthorized`	The bearer token is missing or expired, or has no usable client id.	A problem document.
`403 Forbidden`	The token doesn't grant permission to create shipments.	None.
`409 Conflict`	A request with the same `Idempotency-Key` is still being processed.	A problem document, plus a `Retry-After` header with the seconds to wait.
`422 Unprocessable Entity`	Exactly one shipment was sent and it failed.	A problem document with the failed shipment under `shipment`.
`500 Internal Server Error`	The whole batch was abandoned because of a system issue.	A problem document.

One shipment or many

We use 422 only when the request contained exactly one shipment and that shipment failed.

A request with two or more shipments always returns 200 OK, even when every shipment in it failed. There's no batch-level error status. Check each item's customResponse.hasError to find the ones that failed.

Results come back in the same order as the shipments you sent. When a shipment fails at parcel level, shipmentReference1 isn't echoed, so match the failed shipment by its position in the array.

400 Bad Request

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Invalid request.",
  "status": 400,
  "detail": "Limited to 100 shipments per request."
}

A header problem returns the same shape, with detail set to one of:

The Idempotency-Key header is required.
The Idempotency-Key header must be 8 to 128 characters of letters, digits, underscore, dot, colon or hyphen, and may only be sent once.
This Idempotency-Key has already been used with a different request body.

409 Conflict

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.8",
  "title": "Request already in progress.",
  "status": 409,
  "detail": "This Idempotency-Key is still being processed. Retry with the same key to fetch the result."
}

The Retry-After header gives the number of seconds to wait. Then send the same request again to collect the result. Don't start a second request with a different key, because that would create the shipments twice.

422 Unprocessable Entity

{
  "type": "https://tools.ietf.org/html/rfc4918#section-11.2",
  "title": "The shipment could not be processed.",
  "status": 422,
  "detail": "Route not found",
  "instance": "/api/v1/Shipment/Process",
  "shipment": {
    "customResponse": {
      "hasError": true,
      "errorMessage": "Parcel level issue found"
    },
    "shipmentReference1": "ORD20030824",
    "parcels": [
      {
        "customResponse": {
          "hasError": true,
          "errorMessage": "Route not found"
        },
        "parcelNumber": 1,
        "labels": null
      }
    ]
  }
}

The failed shipment is on the problem document as shipment, in the same shape as an item in the 200 array.

detail is the reason from the shipment. When that reason is Parcel level issue found, detail shows the first failing parcel's message instead, as above.
A shipment that fails before its parcels are processed echoes shipmentReference1 and has an empty parcels array.
A parcel-level failure has Parcel level issue found on the shipment, the real message on the parcel, and shipmentReference1 set to null.

500 Internal Server Error

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
  "title": "An unexpected error occurred.",
  "status": 500,
  "detail": "The shipments could not be processed. Please try again or contact support."
}

No shipment was created. Retry the request with the same Idempotency-Key.

Successful responses

A parcel can have more than one entry in labels. The shipping label has contentType set to Label. When the carrier also returns a customs document, it arrives as a second entry with a different contentType.