Error handling
Deterministic errors make safe agents. What each status code means, what to retry, and why a 409 is your friend.
The one that matters for agents: 409 conflict
Reusing an Idempotency-Key with a different payload returns 409. That is the API refusing to guess: the same key must mean the same order. Retrying the identical request returns the original order (200); changing the payload needs a new key. Full write-up: idempotent orders for AI agents.
Status codes
400— validation failure; fix the request, don't retry as-is401/403— missing/invalid key or scope (403 verification_requiredon the public form means: submit an intake, issuance follows e-mail verification)404— unknown resource id409— idempotency conflict (see above)429— rate limited; honor backoff, see rate limits5xx— server-side; safe to retry when the request carries an idempotency key
Retry policy for agent tools
Retry 408/429/5xx and network errors with exponential backoff — but only on GETs and idempotency-keyed writes. Never blind-retry an un-keyed write. This is exactly the policy built into the OrderCore SDKs and the tool descriptions we recommend for function-calling agents.
Validation guardrails on POST /v1/orders
items: 1–100 entries;quantity1–1000; SKU ids unique per requestcustomer_id,external_id,items[].sku_id: ≤ 255 charsmetadata: ≤ 32 KB JSON