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 three 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	Authentication, not-found, server errors	401, 403, 404, 405, 500
Validation error	Request body failed schema validation	400
Label failure	Courier rejected the label request	502 (also 201/200 with `status: failed`)

Standard error

Returned for authentication failures, not-found errors, and server errors:

{
  "error": "Unauthorized"
}

Validation error

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

{
  "error": "Validation failed",
  "details": [
    {
      "field": "shipment.shipTo.address.countryCode",
      "message": "must be a valid ISO 3166-1 alpha-2 country code"
    },
    {
      "field": "shipment.parcels[0].weight",
      "message": "must be greater than 0"
    }
  ]
}

Each entry in details contains:

Field	Description
`field`	Dot-delimited path to the invalid field (array indices use bracket notation)
`message`	Human-readable description of the validation failure

HTTP status codes

Status	Meaning	When	Retryable
200	OK / Idempotent replay	Successful GET request, or POST with a previously used `idempotencyKey`	N/A
201	Created	Label created successfully	N/A
400	Bad Request	Request body failed validation	No — 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 no access to the requested resource	No — verify account permissions
404	Not Found	Label ID or shipping account does not exist	No — verify the ID
405	Method Not Allowed	HTTP method is not supported for this endpoint	No — check the method
500	Internal Server Error	Unexpected server failure	Yes — retry with backoff
502	Bad Gateway	Courier service returned an error	Yes — retry with backoff

Validation errors (400)

Validation errors indicate that the request body does not meet the API schema requirements. The response always includes a details array with specific field paths. Common causes:

Missing required fields (shipment.shipTo, courier, idempotencyKey)
Invalid field formats (country code, email, phone number)
Invalid numeric values (weight must be greater than 0)

Fix all validation errors listed in the details array 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 caller does not have access to the requested resource. This occurs when attempting to retrieve a label or tracking information that belongs to a different account:

{
  "error": "Forbidden"
}

Downstream courier errors (502)

When the courier service returns an error, 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",
  "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.

Retryable vs non-retryable errors

Error Type	Retryable	Action
400 Validation	No	Fix the request body based on `details`
401 Unauthorized	No	Obtain valid token from the Flex Forward team
403 Forbidden	No	Verify account access to the resource
404 Not Found	No	Verify the label ID or shipping account
500 Server Error	Yes	Retry with the same `idempotencyKey` and exponential backoff
502 Courier Error	Depends	Check error message — transient issues are retryable, validation issues are not

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.flexforward.com (production) or https://sandbox.flexforward.com (development).

Invalid UUID format for label ID

The id parameter in GET /labels/{id} and GET /tracking/{id} must be a valid UUID. Passing a tracking number or other identifier format will return a 404 error.

Label created but status is failed

A status: failed response with HTTP 201 or 200 means the label was persisted but the courier rejected the request. Check the error object 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

Validation errors (400)

Authentication errors (401 / 403)

401 Unauthorized

403 Forbidden

Downstream courier errors (502)

Retryable vs non-retryable errors

Troubleshooting

​Error handling

​Error response formats

​Standard error

​Validation error

​HTTP status codes

​Validation errors (400)

​Authentication errors (401 / 403)

​401 Unauthorized

​403 Forbidden

​Downstream courier errors (502)

​Retryable vs non-retryable errors

​Troubleshooting

Error handling

Error response formats

Standard error

Validation error

HTTP status codes

Validation errors (400)

Authentication errors (401 / 403)

401 Unauthorized

403 Forbidden

Downstream courier errors (502)

Retryable vs non-retryable errors

Troubleshooting