Idempotency and errors

Idempotent creation

external_order_id must be unique within a tenant and acts as the idempotency key.

• The first successful creation returns 201 Created.
• The same order and box return the original shipment and PIN with 200 OK and Idempotent-Replayed: true.
• The same order with another box_id returns 409 idempotency_conflict.

After a timeout, safely repeat the exact request. Do not generate a new external_order_id before reconciling the original request.

Error envelope

{
  "error": {
    "code": "box_full",
    "message": "No customer compartment is currently available.",
    "request_id": "req_4c98d6d9d1f6405a",
    "details": null
  }
}

code is stable and intended for programmatic decisions. message is diagnostic. Include request_id when contacting support; it is also returned in the X-Request-ID response header.

HTTP	Typical codes	Recommended action
401	invalid_api_key	Check the host, key type, and whether it is active.
404	box_not_found, shipment_not_found	Do not retry without correcting the ID.
409	box_full, idempotency_conflict, invalid_transition	Surface the state to an operator or change the input.
422	validation_error	Correct the request using details.
429	rate_limit_exceeded	Wait for Retry-After and add jitter.
5xx	internal_error	Retry with exponential backoff and the same external_order_id.

Request ID

You can send an identifier in X-Request-ID (1 to 80 letters, numbers, ., _, :, or -). EasyPick echoes it back. Otherwise, the API generates one.