Errors

{
  "error": {
    "code": "refused",
    "message": "An inactive or sold-out prepared item cannot be put on sale."
  }
}

Codes

All 20. Each endpoint’s page lists the ones it can answer, with what they mean there.

• ·Possible on every endpoint, so each page prints them once, in a box: missing_api_key, invalid_api_key, rate_limited, internal_error.
• ·Never an endpoint’s own answer, since they mean the path or the method is wrong: unknown_endpoint and method_not_allowed. A 405 lists the methods the path takes in Allow; OPTIONS on a path answers the same list with no key.

When the restaurant says no

409 refused is the restaurant’s own rule speaking: an item that is sold out, a table with an order already open, an order that has taken money. Its message is the sentence the console shows for the same act, except that it never names a guest or a member of staff. Show it to a person; fix what it says; do not retry it unchanged. Each endpoint’s page lists its common refusals.

Retrying

• +429 rate_limited and 409 idempotency_key_in_use: wait Retry-After seconds, then send the same request with the same Idempotency-Key.
• +500 internal_error, a timeout or a dropped connection: send the same request with the same Idempotency-Key. If the first one landed, you get its answer back and nothing runs twice.
• −Any other 4xx: nothing about it changes on a second try. Fix what the message names first; after a refused, send the corrected request with a new key.

Kept and released under an Idempotency-Key

A write’s answer is kept against its Idempotency-Key, so a retry gets the same answer: a success, 404 not_found and 409 refused. 422 invalid_request and a 5xx are released: correct the body, or retry, with the same key. A request refused before its key is read (a 400, 401, 403, 413, 415 or 429) does not use the key up. See Idempotency.

Reading an error

Branch on error.code, never on the message. Check the content type before parsing: a proxy or a load balancer can answer before the API does, and its page is not JSON.

const response = await fetch(url, init);
// A proxy's error page is not JSON: read the body as JSON only when it says so.
const isJson = response.headers.get("content-type")?.includes("application/json");
const body = isJson ? await response.json() : null;

if (!response.ok) {
  const code = body?.error?.code;
  if (code === "rate_limited" || code === "idempotency_key_in_use") {
    // Wait Retry-After seconds, then send the same request, same Idempotency-Key.
  } else if (code === "refused") {
    // The restaurant's own rule: show body.error.message to a person.
  }
  throw new Error(body?.error ? `${code}: ${body.error.message}` : `HTTP ${response.status}`);
}

response = requests.post(url, headers=headers, json=payload, timeout=30)

# Not raise_for_status(): it drops error.message, the sentence that says what to fix.
body = response.json() if response.headers.get("content-type", "").startswith("application/json") else None
if not response.ok:
    code = body["error"]["code"] if body and "error" in body else None
    if code in ("rate_limited", "idempotency_key_in_use"):
        ...  # wait Retry-After seconds, then send the same request, same Idempotency-Key
    elif code == "refused":
        ...  # the restaurant's own rule: show body["error"]["message"] to a person
    raise SystemExit(f"{code}: {body['error']['message']}" if code else f"HTTP {response.status_code}")