Skip to main content

​
Idempotency and retries

Shipping labels have real-world cost and logistics impact. Duplicate labels cause operational confusion, wasted shipping spend, and inventory tracking errors. The Flex Forward API provides built-in idempotency to prevent this.

​
How idempotency works

The POST /labels endpoint uses the idempotencyKey field to ensure that each label creation request is processed exactly once. First request — the API creates the label and returns HTTP 201:
201 Created
Replayed request — the same idempotencyKey returns the original result with HTTP 200, without creating a new label:
200 OK (idempotent replay)
The idempotency key is scoped to your API account. Two different accounts can use the same key without collision.

​
Choosing an idempotency key

The key should uniquely identify the intended label creation. Good patterns:
Never generate a new idempotencyKey when retrying the same logical request. Reuse the original key so the API can detect the duplicate.
After a 400 validation error, the same idempotencyKey can be reused because no label was created. Fix the request and retry with the same key.

​
Retry strategy

For transient failures (HTTP 500, 502, or network timeouts), retry with exponential backoff:
1

Set a request timeout

Use a reasonable timeout for the HTTP request (e.g., 30 seconds).
2

On failure, wait before retrying

Use exponential backoff: 1 second, 2 seconds, 4 seconds, 8 seconds.
3

Reuse the same idempotency key

Always retry with the same idempotencyKey as the original request. This ensures no duplicate label is created even if the original request succeeded but the response was lost.
4

Cap the retry count

Stop after 3–5 retries. If the request still fails, log the error and escalate for investigation.

​
Idempotency by endpoint

​
Failure scenarios

The label may or may not have been created. Retry with the same idempotencyKey. If the label was created, the API returns HTTP 200 with the original result. If not, it creates the label and returns HTTP 201.
A transient server error. Retry with backoff using the same idempotencyKey.
The courier service returned an error. The label is persisted with status: failed. Check the error message before retrying — some courier errors require changes to the request (e.g., invalid address). For transient courier issues, retry with the same idempotencyKey.
The request is invalid. Do not retry without fixing the request. The same idempotencyKey can be reused after correcting the request body because no label was created.