Errors

Every error is JSON. Quote-endpoint errors carry { "error": "..." }; plan-endpoint errors add a stable code field. All bodies below were captured from production on 2026-07-03. Error responses are never cached.

Taxonomy

status	when	example body
400	Validation: bad params, missing fields, fee rules, keyed-only features without a key.	`{"error":"integrator fees require an API key"}`
401	A key was presented and is malformed, unknown, revoked, or fails verification.	`{"error":"invalid API key"}`
429	Over the per-key or per-IP limit. Carries `Retry-After` (seconds to the window reset) and the `X-RateLimit-*` headers. Blocked, never billed.	`{"error":"rate limit exceeded"}`
500	Unexpected failure. Nothing was created; safe to retry.	`{"error":"..."}`
503	Your key could not be VERIFIED because the verification infrastructure was unreachable. Your key is fine; retry after the `Retry-After` seconds. This is deliberately distinct from 401: an infra failure never reads as "your key is bad".	`{"error":"key verification is temporarily unavailable"}`

 A real 429, captured with a deliberately rate-limited key:
 HTTP/2 429
retry-after: 49
x-ratelimit-limit: 1
x-ratelimit-remaining: 0

{"error":"rate limit exceeded"}
 Captured from production 2026-07-03.
 Plan-endpoint codes
  POST /api/execute/plan adds a machine-readable
code: missing_key, bad_request,
unknown_token, bad_party,
bad_fee_params, no_pool (400);
venue_unavailable (409); quote_failed (502);
internal (500). Full table in the
plan reference. Captured examples:
 {"error":"execution planning requires an API key","code":"missing_key"}
{"error":"takerParty must be a Canton party id","code":"bad_party"}
{"error":"venue cantonswap is not available for this pair","code":"venue_unavailable"}
 The failure playbook
   400: fix the request; do not retry unchanged.
  401: check the key; if it should be valid, contact us.
503: retry with backoff; the key is not the problem.
  429: wait Retry-After seconds. Do not tight-loop; the window
      is a fixed minute.
  409 venue_unavailable: re-quote, choose a venue from
      the fresh quote, re-plan.
  Plan expired before the deposit went out: re-plan with a NEW
      idempotency key. The old plan is dead; its floor no longer matches the
      market.
  Execution failures after the deposit (slippage, refund, abort) are lifecycle
      states, not HTTP errors: see the
execution lifecycle. The design principle: a
      worse-than-quoted price causes an abort and a refund, not a loss.