Errors

Every error response shares the same envelope:

{
  "success": false,
  "message": "Human readable summary.",
  "errorCode": "order.not_found",
  "details": {
    "orderId": "ord_01HZX..."
  },
  "traceId": "00-7f3b...-01"
}

Branch on code, never on message — the latter is localised and may change without notice.

Status code matrix

Status	When	Retryable?
400	Validation failure	No
401	Missing / expired token	After refresh
403	Scope or tenant denied	No
404	Resource not found	No
409	Conflict / idempotency mismatch	No
422	Business rule violation	No
429	Rate limited	Yes (respect Retry-After)
5xx	Server-side	Yes (exponential backoff)

Common error codes

The numeric values below are returned in the response envelope's ErrorCode field for business-rule failures. Use them to branch your client logic.

Code	When it's returned
-1	The order request failed basic validation (malformed payload or missing mandatory fields).
-2	The referenced order line could not be located while attempting delivery.
-3	The external order has already been marked as delivered and cannot be delivered again.
-4	The order has already been cancelled and can no longer be updated or delivered.
-5	The order line is currently being processed by another worker. Retry after a short delay.
-6	The request did not include the external product identifier.
-7	No product matched the supplied identifier while preparing the delivery.
-8	The supplied external product identifier is malformed or not recognised.
-9	The specified external product line has already been delivered for this order.
-10	The cancellation quantity is greater than the remaining cancellable quantity on the line.
-11	The delivery request was accepted but contained no items to deliver.
-12	Generic, non-classified failure. Inspect the response message and traceId for context.
-13	Delivery data did not conform to the expected schema for the target product.
-14	The delivery flow could not determine which step to execute (step value missing).
-15	The supplied region / locale code could not be resolved.
-16	The customer profile is missing fields that are required for the requested operation.
-17	No customer record matches the supplied identifier.
-18	The customer exists but no API integration record is configured for them.
-19	The basket contains no items; an order cannot be created from it.
-20	The basket changed between read and checkout. Re-fetch it before retrying.
-21	The customer's available balance is lower than the order total.
-22	A delivery with the same identifier has already been submitted (idempotency conflict).
-23	The provided API key is missing, expired, revoked, or does not belong to the requested tenant.

Tracing

Always include the traceId when contacting support — it identifies the request across all internal services.