Errors

What failures look like, and how to handle them.

When something goes wrong, you always get back the same shape, so you only have to handle it in one place:

{
  "error": {
    "code": "insufficient_scope",
    "message": "API key lacks required scope: product::create",
    "request_id": "0f9c…"
  }
}

• code is a short, stable label — branch your logic on this.
• message is a plain-English explanation for people. It can change, so don’t write code that depends on its exact wording.
• request_id is worth logging. If you ever need our help, sending it lets us find the exact request.

What the codes mean

Status	Code	What happened
400	bad_request	The body or query parameters didn’t make sense.
401	invalid_api_key	The key is missing, wrong, or inactive.
403	insufficient_scope	The key isn’t allowed to do this.
403	plan_required	The workspace’s plan doesn’t include the API.
404	not_found	That resource doesn’t exist in this workspace.
409	conflict	It clashes with something that already exists, like a duplicate name or SKU.
422	unprocessable	We could read the request, but it didn’t pass validation.
429	rate_limited	You’re sending requests too fast — see Rate limits.
5xx	internal_error	Something broke on our end. It’s safe to try again in a moment.

Handling them in code

Look at code and react to the cases you care about:

const res = await fetch(url, { headers });

if (!res.ok) {
  const { error } = await res.json();

  if (error.code === "rate_limited") {
    // wait and retry — see the Rate limits page
  } else if (error.code === "insufficient_scope" || error.code === "plan_required") {
    // retrying won't help; show a clear message instead
  } else {
    // log error.request_id so support can trace it
  }
}