Errors and limits

Errors have one shape. The code is for your program. The error is a sentence you can show to a person.

JSON

{
  "ok": false,
  "code": "missing_scope",
  "error": "This key cannot read orders.",
  "request_id": "req_0123456789abcdef0123"
}

Codes

HTTP	code	Meaning
400	`bad_request`	Bad JSON or a bad query.
401	`invalid_key`	The key is unknown, stopped or badly formed.
403	`missing_scope`	The key lacks the scope for this call.
403	`browser_not_allowed`	A secret or legacy key was used from a browser.
403	`origin_not_allowed`	The browser origin does not match the company website.
403	`company_inactive`	The company is switched off.
404	`not_found`	No such path, order or endpoint.
405	`method_not_allowed`	Wrong method for this path.
409	`conflict`	The request clashes with the current state.
413	`too_large`	The body is too big. JSON is up to 64 KB. Screenshots are up to 8 MB.
422	`invalid`	A business rule refused the request. The `error` sentence says why and can be shown to the shopper.
429	`rate_limited`	Too many calls. Wait and try again.
500	`server_error`	Our fault. No detail is given. Try again, then contact us with the request id.

Request ids

Every response has an X-Request-Id header. Errors also carry it as request_id. Send us this id when you ask for help. It lets us find your call.

Rate limits

Key	Per minute
Publishable	120
Secret	600
Legacy shop key	600

Limits are counted per key. Over the limit you get 429 with Retry-After: 60. There is also a per-address limit at the edge of 300 calls per 60 seconds. It answers 429 in the same shape.

JavaScript

async function call(url, options, tries = 3) {
  const res = await fetch(url, options);
  if (res.status === 429 && tries > 1) {
    const wait = Number(res.headers.get("Retry-After") || 60);
    await new Promise(r => setTimeout(r, wait * 1000));
    return call(url, options, tries - 1);
  }
  return res;
}

Cache the catalog for about a minute instead of reading it on every page view.

Xatern One API v1. Example data on these pages is made up.