Errors

The error object, error types and HTTP statuses, which errors to retry, and how to debug with request ids.

Errors use conventional HTTP statuses (2xx success, 4xx a problem with the request, 5xx a problem on our side) and always have the same JSON body:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid items[0].quantity: must be greater than or equal to 1.",
    "param": "items[0].quantity",
    "doc_url": "https://swaglists.com/docs/errors#parameter_invalid",
    "request_id": "req_01k8x4b2q7w9e1r3t5y7u9i1o3",
    "errors": [
      { "param": "items[0].quantity", "code": "parameter_invalid", "message": "Invalid items[0].quantity: must be greater than or equal to 1." },
      { "param": "recipient.country_code", "code": "parameter_invalid", "message": "Invalid recipient.country_code: must be an ISO 3166-1 alpha-2 country code." }
    ]
  }
}

Some errors carry extra fields:

New fields may be added to the error object at any time — ignore the ones you don't use.

#Types and statuses

404 vs 400 for missing objects: a 404 means the object in the URL does not exist (GET /orders/ord_unknown). An unknown object referenced in the body (an unknown sku, file_id, catalog_variant_id) is a 400 with code: resource_missing and param pointing at it.

#Handling errors in code

const res = await fetch("https://swaglists.com/api/v1/orders", { method: "POST", headers, body: JSON.stringify(order) });
const body = await res.json();
if (!res.ok) {
  const { code, message, param, request_id } = body.error;
  switch (code) {
    case "duplicate_external_id":
      return body.error.existing_id; // already forwarded — treat as success
    case "resource_missing":
      if (param?.endsWith(".sku")) return skipUnknownSku(param); // not one of your products
      break;
    case "insufficient_funds":
      return alertFinance(body.error.required_amount, body.error.available_amount);
  }
  console.error(`API error ${res.status} ${code} (${param ?? "-"}): ${message} [${request_id}]`);
  throw new Error(code);
}

res = requests.post("https://swaglists.com/api/v1/orders", json=order, headers=headers)
if not res.ok:
    error = res.json()["error"]
    if error["code"] == "duplicate_external_id":
        return error["existing_id"]  # already forwarded — treat as success
    logger.error("API error %s %s (%s): %s [%s]", res.status_code, error["code"], error.get("param"), error["message"], error["request_id"])
    raise RuntimeError(error["code"])

#What to retry

• Retry network errors, timeouts, 429 (wait Retry-After seconds), 409 idempotency_in_progress (wait 1 second) and 5xx — with exponential backoff and jitter, and the same Idempotency-Key, so a request that actually succeeded is not repeated. See the retry recipe.
• Don't retry other 4xx errors unchanged — they will fail again. Fix the request, or surface the problem (log it with request_id, alert, or show it in your back office).
• After fixing a 4xx, send the request with a new Idempotency-Key — also when the fix happened outside the request, such as adding credits after 402 insufficient_funds or creating a missing SKU. A request that ran is stored with its key for 24 hours, so a retry with the original key returns the original error again (with Idempotent-Replayed: true). Derive the new key from the old one (order-1042:2); external_id still prevents a duplicate order.

#Validation messages

parameter_invalid messages name the rule that failed:

#Debugging

• Every response has a Request-Id header (req_…); errors repeat it as request_id.
• Developers → Logs in the dashboard shows recent requests with status, error code, duration and (redacted) bodies — search by request id.
• Responses also carry Api-Version (the API version that served the request).

The complete list of codes, with what each means and how to fix it, is the error reference.