Start

Errors

Every error has the same shape: a machine-readable code, a short message written by the server (never by an AI model), and a reason_code when a business rule made the decision.

Example error body

{
  "error": {
    "code": "conflict",
    "message": "That pickup window is full.",
    "reason_code": "window_full"
  }
}

Show your own copy keyed by code and reason_code; use message for logs. Retry a failed write with the same command_id and idempotency_key — a replay of an accepted command returns the original result.

HTTP statuses

Status	Meaning
`400`	The request is malformed (bad JSON, a bad path or query value).
`401`	No valid credential was sent where one is required.
`403`	The caller is known but not allowed to do this (role or outlet scope).
`404`	Not found — and also the answer to a bad storefront key or guest token, so keys cannot be probed.
`409`	A conflict with the current state: an order already moved on, a full pickup window, a repeated idempotency key with a different body.
`422`	The body is well-formed but fails validation or a business rule; reason_code says which.

Error codes (31)

The full set of error.code values in the OpenAPI file.

bad_request
unauthenticated
forbidden
not_found
conflict
book_write_refused
country_locked
currency_mismatch
illegal_transition
override_refused
decision_refused
customer_erased
command_table_mismatch
period_closed
books_unbalanced
loyalty_refused
claim_quote_mismatch
out_of_pack_scope
sequence_gap
investigation_refused
idempotency_conflict
command_type_mismatch
invalid_payload
unregistered_command_type
cannot_verify
already_decided
stale_draft
chart_incomplete
execution_failed
unavailable
internal

Reason codes (89)

The full set of reason_code values. The same list explains why an AI answer says "Cannot verify" (see the AI contract) — for example missing_ref or settlements_missing. Storefronts mostly meet the ordering ones: window_full, item_sold_out, outlet_paused, coupon_invalid, preview_total_changed.

number_grammar
unresolved_ref
cross_tenant_ref
quote_mismatch
missing_ref
settlements_missing
recipe_missing
stale_draft
authority_denied
cost_price_missing
ticket_times_missing
count_missing
expiry_missing
budget_exceeded
budget_missing
margin_below_floor
moq_exceeds_need
open_commitment_overlap
payment_terms_worse
consent_record_missing
bank_lines_missing
attendance_missing
payroll_out_of_scope
no_marketing_consent
not_a_certificate
log_coverage_missing
signal_source_missing
insufficient_history
forecast_stale
window_full
outlet_paused
item_sold_out
deal_rejudged
coupon_invalid
coupon_cap_reached
coupon_min_spend
change_window_closed
coupon_expired
coupon_out_of_scope
price_above_mrp
expired_batch
period_closed
model_blocked
preview_total_changed
buyer_identity_required
tax_id_missing
unknown_tax_class
unknown_channel
unit_mismatch
not_applicable
item_unavailable
reason_required
deal_changed
duplicate_invoice
guest_cannot_change
refund_first
order_tendered
cash_below_rounding
recently_rejected
mode_above_ceiling
cap_above_platform_budget
platform_budget_missing
assignee_missing
campaign_audience_unscoped
specialist_needed
cares_not_available
cares_not_enabled
cares_not_opted_in
cares_city_mismatch
recipient_ineligible
listing_expired
qty_exceeds_on_hand
qty_exceeds_listed
cooked_hold_exceeded
line_expired
no_eligible_recipient
no_rostered_staff
offer_not_enabled
offer_closed
claim_decided
claim_received
rate_limited
handover_must_be_complete
offer_handover_final
pickup_time_outside_window
theme_contrast
page_version_stale
demo_only
demo_protected

Draft decision errors

Approving or rejecting a draft can fail with an extended body:

DraftsDecisionErrorcontract drafts.decision-error

errorobjectrequired
- codeenum (7)required
  invalid_payloadunregistered_command_typecannot_verifyalready_decidedstale_draftidempotency_conflictexecution_failed
- messagestringrequired
  min length 1max length 500
- reason_codeReasonCode | nullrequired
changesarray of objectoptional
- refstringrequired
  pattern ^⟨snap:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}·(?:0|[1-9][0-9]*)·[a-z_][a-z0-9_]*⟩$
- valueone of 3 | nullrequired
- now_refstring | nullrequired
  pattern ^⟨snap:[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}·(?:0|[1-9][0-9]*)·[a-z_][a-z0-9_]*⟩$
- nowone of 3 | nullrequired
refsarray of stringoptional