Errors - EXC

The two APIs return different error shapes. If you’re consuming both, handle them separately.

Marketplace API

A structured envelope with a code you can branch on:

{
  "error": {
    "code": "not_found",
    "message": "Collection not found."
  }
}

Code	Status
`bad_request`	400	Bad parameters
`not_found`	404	No such collection or token
`rate_limited`	429	Too many requests
`upstream_error`	502	A data source failed

Branch on error.code, not the message — messages are for humans and may get reworded. On a 502 the message is deliberately generic. Upstream error text isn’t passed through, because it can contain query internals. Retry, and tell us if it persists.

Store API

A flat string:

{
  "error": "Insufficient permissions. Required scope: products:write"
}

Status
`400`	Bad payload or parameters
`401`	Missing, invalid, disabled or expired key
`403`	Valid key, wrong scope
`404`	Not in your shop
`429`	Too many requests
`500`	Our problem

Handling both

async function request(url, options) {
  const res = await fetch(url, options);
  const body = await res.json().catch(() => null);

  if (res.ok) return body;

  // Marketplace: { error: { code, message } }
  // Store:       { error: "message" }
  const err = body?.error;
  const code = typeof err === 'object' ? err.code : null;
  const message = typeof err === 'object' ? err.message : err;

  throw Object.assign(new Error(message ?? res.statusText), {
    status: res.status,
    code,
  });
}

What’s worth retrying

Status	Retry
`400`, `403`, `404`	No — the request is wrong, and repeating it repeats the mistake
`401`	No, unless you’re mid key-rotation
`429`	Yes, honouring `Retry-After`
`500`, `502`	Yes, backing off

→ Rate limits has a backoff implementation.

Opaque 400s

Store API payload validation is strict but reports generically — "Invalid product payload" rather than naming the field.

Post the minimum viable payload first, then add fields back one at a time. Each endpoint page lists what’s actually required.

​Marketplace API

​Store API

​Handling both

​What’s worth retrying

​Opaque 400s

Marketplace API

Store API

Handling both

What’s worth retrying

Opaque 400s