Error handling

The Flex Forward API uses standard HTTP status codes and structured error responses. This page covers the error formats, status code meanings, and guidance for handling failures.

Error response formats

The API returns four error response shapes depending on the type of failure. Understanding which shape to expect helps you write correct error-parsing logic.

Shape	When	Status Codes
Standard error	Unsupported courier/product, authentication, not-found, conflict, rate-limit, or server errors	400, 401, 403, 404, 409, 429, 500; 502 on GET endpoints
Validation error	Request body failed schema validation	400
Label failure	Courier rejected the label request; `LabelResponse` with `status: failed`	502 on `POST /labels`, or 200 when an idempotent replay returns a stored failed attempt
Failed-label read	Reading a label whose courier submission failed; `LabelFailedResponse`	422 on `GET /labels/{id}` and `GET /tracking/{id}`

Standard error

Returned for failures such as unsupported couriers/products, authentication failures, conflicts, not-found errors, and server errors. The shape is { "error": string, "code"?: string }:

{
  "error": "Label not found"
}

The error text is informational and may change without notice. Branch on the HTTP status code and, where present, code — never on the message text. Some errors include a machine-readable code. The following codes distinguish label-creation conflicts from courier failures:

`code`	Meaning
`IDEMPOTENCY_CONFLICT`	HTTP 409: the key was used with a different request body. Use the original body for a replay, or a new key for the changed request.
`DUPLICATE_CUSTOMER_ORDER_NUMBER`	HTTP 409: the order number already exists for your account. Retrieve that label, or use a different order number for a new label.
`COURIER_ERROR`	The courier rejected the label request. This is nested under `error.code` in the label response on HTTP 502, or returned as `errorCode` on failed-label reads.

The code field is optional and this list is not exhaustive. Handle errors without a code using their HTTP status, and tolerate unknown codes.

Validation error

Returned for request validation failures (HTTP 400). Includes a details array with field-level error information:

{
  "error": "Validation failed",
  "details": [
    {
      "field": "shipment.parcels.0.weight",
      "message": "must be >= 0"
    }
  ]
}

Each entry in details contains:

Field	Description
`field`	Dot-delimited path to the invalid field. Array indices are dot-delimited numbers, e.g. `shipment.parcels.0.weight`.
`message`	Human-readable description of the validation failure

Only the first validation error is returned. Fix it and resend to surface the next one. HTTP 400 can also use the standard error shape, for example when a courier or product is unsupported. Check whether details exists before reading it; do not assume every 400 contains field-level errors.

HTTP status codes

Status	Meaning	When	Retryable
200	OK / Idempotent replay	Successful GET request, or `POST /labels` replaying the same key and body. The stored result may have `status: failed`	N/A
201	Created	Label created successfully	N/A
400	Bad Request	Invalid request body or unsupported courier/product	No — inspect `details` when present, otherwise `error` and optional `code`, then fix the request
401	Unauthorized	Missing or invalid `x-rr-apikey` / `x-rr-apitoken`	No — obtain valid credentials from the User Portal
403	Forbidden	Valid credentials but the account is not permitted (for example, blocked)	No — verify account permissions
404	Not Found	Label ID or shipping account does not exist	No — verify the ID
409	Conflict	Key reused with a different body, or order number already exists (`POST /labels`)	No — inspect `code` and follow the conflict guidance above
422	Unprocessable Entity	The label exists but courier submission failed; no document or tracking is available (`GET /labels/{id}`, `GET /tracking/{id}`)	No — create a new label
429	Too Many Requests	Request rate for the account was exceeded. Declared on every endpoint so clients implement handling ahead of enforcement (see Rate limits)	Yes — wait for the number of seconds in the `Retry-After` header, then retry
500	Internal Server Error	Unexpected server failure	Yes — retry with backoff
502	Bad Gateway	Courier rejected the label request; the label is stored with `status: failed`	Not with the same `idempotencyKey` — fix the cause, then send a new request (see Retrying a failed label)

Label creation outcomes

POST /labels returns the same LabelResponse shape on 200, 201, and 502. The HTTP status code tells you whether this call created the label, replayed an earlier attempt, or was rejected by the courier. The status field tells you whether a label exists.

On POST /labels, branch on the status field, not on the HTTP status code. An idempotent replay returns HTTP 200 even when the first attempt failed at the courier, so a 200 response can carry status: failed.

HTTP	`status`	`error`	Meaning	Action
201	`created`	`null`	Label created at the courier on this call	Store `id`; continue to document retrieval and tracking
200	`created`	`null`	Replay of an earlier successful attempt	Same as 201 — no new label was created
200	`failed`	object	Replay of an earlier attempt that the courier rejected	Do not retry with the same key; see Retrying a failed label
502	`failed`	object	The courier rejected this request; the attempt is stored under your `idempotencyKey`	Read `error.message`, fix the request, resend with a new `idempotencyKey` and `customerOrderNumber`

Validation errors (400)

Schema validation errors indicate that the request body does not meet the API requirements and include a details array with specific field paths. Other HTTP 400 errors use the standard error shape without details. Common causes:

Missing required fields (shipment.shipTo, courier, idempotencyKey)
Wrong field types or lengths (for example countryCode must be exactly 2 characters)
Negative numeric values (weight and dimensions must not be negative)
An invalid order.customerOrderNumber (maximum 40 characters, using only ASCII letters, digits, -, and _)
An unsupported label.format (use PDF or PNG) or item unitPrice.currency (only USD is accepted)

Fix the reported error before retrying. The same idempotencyKey can be reused after a 400 response because no label was created.

Authentication errors (401 / 403)

401 Unauthorized

The x-rr-apikey or x-rr-apitoken header is missing or invalid:

{
  "error": "unauthorized"
}

Verify that both headers are present:

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN

403 Forbidden

The credentials are valid but the account is not permitted to call the API (for example, a blocked account):

{
  "error": "Forbidden: account is blocked"
}

A label or tracking record that belongs to a different account returns 404, not 403.

Downstream courier errors (502 and 422)

When the courier service returns an error during POST /labels, the API responds with HTTP 502. The label is persisted in the database with status: failed and includes the courier error details:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "customerOrderNumber": "N-2026-05-27-TEST-03",
  "status": "failed",
  "courier": "yunexpress",
  "courierOrderNumber": null,
  "courierTrackingNumber": null,
  "error": {
    "code": "COURIER_ERROR",
    "message": "Address validation failed at courier"
  }
}

The error object contains:

Field	Description
`code`	Machine-readable error code
`message`	Human-readable error description from the courier

A 502 response means the label request reached the courier and was rejected. Before retrying, review the error message — some courier errors (e.g., address validation) are not transient and require request changes.

Later calls to GET /labels/{id} or GET /tracking/{id} for a failed label return HTTP 422 with a LabelFailedResponse body — no document or tracking is available for that label:

{
  "error": "Label creation failed",
  "errorCode": "COURIER_ERROR",
  "errorMessage": "Address validation failed at courier"
}

Retryable vs non-retryable errors

Error Type	Retryable	Action
400 Bad Request	No	Fix the request using `details` when present, otherwise `error` and optional `code`
401 Unauthorized	No	Get valid credentials from the User Portal (Settings → Signing Key and API Token)
403 Forbidden	No	Verify account access to the resource
404 Not Found	No	Verify the label ID or shipping account
409 Conflict	No	For `IDEMPOTENCY_CONFLICT`, use the original body or a new key; for `DUPLICATE_CUSTOMER_ORDER_NUMBER`, retrieve the existing label or choose another order number
422 Unprocessable Entity	No	The label failed courier submission — create a new label
429 Too Many Requests	Yes	Wait for `Retry-After` seconds, then retry with the same `idempotencyKey`
500 Server Error	Yes	Retry with the same `idempotencyKey` and exponential backoff
502 Courier Error	Not with the same key	Fix the cause, then send a new request with a new `idempotencyKey` and `customerOrderNumber` — see Retrying a failed label

See Idempotency and Retries for the recommended retry strategy.

Troubleshooting

Missing Content-Type header

All POST requests must include Content-Type: application/json. Without it, the request body will not be parsed and the API returns a 400 error.

Wrong base URL or HTTP instead of HTTPS

All requests must use HTTPS. Verify you are using the correct environment URL: https://api.flexforwardship.com (production) or https://sandbox.flexforwardship.com (development).

Identifier not found

The id parameter in GET /labels/{id} and GET /tracking/{id} accepts a label UUID or your customerOrderNumber. Any other value, or an identifier from another account, returns a 404 error.

Label created but status is failed

A status: failed response is returned with HTTP 502 from POST /labels (or with HTTP 200 when you replay the same idempotencyKey), and later reads of that label return HTTP 422. Check the error object (or the LabelFailedResponse body on reads) for the courier’s error message. Common causes: invalid address, unsupported destination, or courier account configuration issues.

Getting Started

Guides

Use-Case Guides

Platform

Error Handling

Error handling

Error response formats

Standard error

Validation error

HTTP status codes

Label creation outcomes

Validation errors (400)

Authentication errors (401 / 403)

401 Unauthorized

403 Forbidden

Downstream courier errors (502 and 422)

Retryable vs non-retryable errors

Troubleshooting

​Error handling

​Error response formats

​Standard error

​Validation error

​HTTP status codes

​Label creation outcomes

​Validation errors (400)

​Authentication errors (401 / 403)

​401 Unauthorized

​403 Forbidden

​Downstream courier errors (502 and 422)

​Retryable vs non-retryable errors

​Troubleshooting

Error handling

Error response formats

Standard error

Validation error

HTTP status codes

Label creation outcomes

Validation errors (400)

Authentication errors (401 / 403)

401 Unauthorized

403 Forbidden

Downstream courier errors (502 and 422)

Retryable vs non-retryable errors

Troubleshooting