Skip to main content

Errors & Status Codes

The Weave API uses standard HTTP status codes and wraps every response in a consistent JSON envelope.

The response envelope​

A successful response carries your result under data:

{
  "success": true,
  "eventId": "…",
  "eventDateTime": "…",
  "data": { "customerId": "…" }
}

When a request fails, success is false and the problem is described in an errors array:

{
  "success": false,
  "errors": [{ "code": 1001, "message": "A human-readable description of what went wrong." }]
}

Check the HTTP status first, then read errors[0].message for detail. Rate-limit, overload and billing errors also set errors[0].description to a stable reason (RATE_LIMITED, SERVICE_OVERLOADED or PAYMENT_REQUIRED) you can branch on.

Common status codes​

StatusMeaning
200Success. The result is under data.
400Invalid input — a required field is missing or a value is malformed. Fix and retry.
401Missing or invalid credentials. Check your Authorization header and API key.
402Payment required (PAYMENT_REQUIRED). The organization's billing has lapsed, so writes are refused until it is fixed; see Billing.
403Authenticated, but not permitted to perform this operation. Check the key's roles.
404The resource doesn't exist (or isn't visible to you).
409Conflict — the request collides with existing state (e.g. the target is still referenced by other entities).
429Rate limited (RATE_LIMITED). Wait for Retry-After, then retry; see Rate Limits.
503Briefly overloaded (SERVICE_OVERLOADED). Wait for Retry-After, then retry; see Rate Limits.

A 5xx status indicates an unexpected error on our side; these are safe to retry with backoff.

Handling errors​

const response = await fetch("https://api.loomloyalty.com/customers/does-not-exist", {
  headers: { Authorization: `Bearer ${process.env.LOOM_API_KEY}` },
});

const body = await response.json();

if (!response.ok || body.success === false) {
  const message = body.errors?.[0]?.message ?? response.statusText;
  throw new Error(`Weave API ${response.status}: ${message}`);
}

// Use body.data
  • Treat any non-2xx status, or success: false, as a failure.
  • Log errors[0].code (a numeric code) and message — the code is stable enough to branch on, the message is for humans.
  • Retry 429 and 5xx responses with exponential backoff; don't retry 4xx client errors without changing the request.
  • Don't retry a 402: it won't succeed until someone fixes the organization's billing on the Dashboard's Billing page. Reads keep working in the meantime.

Next Steps​