Errors

Machine-readable codes. Request errors abort the whole call; item errors leave the rest of the batch free to accept.

---

Request errors

Code	HTTP	Meaning
unauthorized	401	Missing, invalid, or revoked key
forbidden_scope	403	Valid key, wrong kind or missing scope (pk_plp_ on a write route)
rate_limited	429	Over limit; see Retry-After + X-RateLimit-*
malformed_json	400	Body is not valid JSON
batch_too_large	400	More than 250 orders (or spend batch cap)
payload_too_large	413	Body over 4 MB
unknown_source	409	Orders before PUT /v1/source
source_locked	409	Currency/timezone change after first accepted order

Error body shape: { "error": string, "code"?: string }.

---

Item errors

Returned inside the batch result; the HTTP status is still 200 when the request itself is well-formed.

Code	Meaning
money_must_be_string	JSON number in a money field
money_invalid / money_scale	Regex or scale violation
sum_mismatch	Identity failure; detail includes computed vs supplied
rounding_adjustment_too_large	Beyond currency cash-rounding bound
refunds_exceed_order	Sum of refund totals > order total
refund_split_exceeds_total	tax + shipping portions > refund total
refund_line_exceeds_order	Refund line qty > order line qty
timestamp_missing_offset	Bare local timestamp
timestamp_in_future	More than 48h ahead of server clock
duplicate_in_batch	Same natural key twice with differing payloads
duplicate_line_id	line_id not unique within the order
pii_rejected	customer.id looks like PII
unknown_field	Request field not in the v1 schema
expense_invalid	Expense validation failure

superseded is an outcome, not an error: older updated_at acknowledged as a no-op.