Skip to main content

​
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.
ShapeWhenStatus Codes
Standard errorAuthentication, not-found, server errors401, 403, 404, 405, 500
Validation errorRequest body failed schema validation400
Label failureCourier rejected the label request502 (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:
FieldDescription
fieldDot-delimited path to the invalid field (array indices use bracket notation)
messageHuman-readable description of the validation failure

​
HTTP status codes

StatusMeaningWhenRetryable
200OK / Idempotent replaySuccessful GET request, or POST with a previously used idempotencyKeyN/A
201CreatedLabel created successfullyN/A
400Bad RequestRequest body failed validationNo — fix the request
401UnauthorizedMissing or invalid Bearer tokenNo — obtain valid token from Flex Forward team
403ForbiddenValid token but no access to the requested resourceNo — verify account permissions
404Not FoundLabel ID or shipping account does not existNo — verify the ID
405Method Not AllowedHTTP method is not supported for this endpointNo — check the method
500Internal Server ErrorUnexpected server failureYes — retry with backoff
502Bad GatewayCourier service returned an errorYes — 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 Bearer token is missing, malformed, or expired: 
{
  "error": "Unauthorized"
}
Verify that the Authorization header is present and correctly formatted: Bearer YOUR_API_TOKEN.

​
403 Forbidden

The token is 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:
FieldDescription
codeMachine-readable error code
messageHuman-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 TypeRetryableAction
400 ValidationNoFix the request body based on details
401 UnauthorizedNoObtain valid token from the Flex Forward team
403 ForbiddenNoVerify account access to the resource
404 Not FoundNoVerify the label ID or shipping account
500 Server ErrorYesRetry with the same idempotencyKey and exponential backoff
502 Courier ErrorDependsCheck error message — transient issues are retryable, validation issues are not
See Idempotency and Retries for the recommended retry strategy.

​
Troubleshooting

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.
All requests must use HTTPS. Verify you are using the correct environment URL: https://api.flexforward.com (production) or https://sandbox.flexforward.com (development).
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.
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.