Error Handling

All error responses follow this structure:

{
  "error": {
    "code": "not_found",
    "message": "Party with ID 'party_invalid' not found.",
    "details": {
      // Optional additional context
    }
  },
  "meta": {
    "requestId": "req_abc123xyz"
  }
}

Always include the requestId when contacting support—it lets us trace the exact request through our systems.

For transient errors (429, 5xx), implement exponential backoff with jitter:

async function fetchWithRetry(url, options, maxRetries = 3) {
  let lastError;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const res = await fetch(url, options);

      if (res.status === 429) {
        // Out of retries — surface the throttle to the caller instead
        // of falling out of the loop with no return value.
        if (attempt === maxRetries) {
          throw new Error(`Rate limited after ${maxRetries + 1} attempts`);
        }
        const retryAfter = res.headers.get("Retry-After") || "1";
        await sleep(parseInt(retryAfter, 10) * 1000);
        continue;
      }

      if (res.status >= 500) {
        throw new Error(`Server error: ${res.status}`);
      }

      return res;
    } catch (err) {
      lastError = err;
      if (attempt === maxRetries) throw err;

      // Exponential backoff with jitter
      const baseDelay = Math.pow(2, attempt) * 1000;
      const jitter = Math.random() * 1000;
      await sleep(baseDelay + jitter);
    }
  }

  // Belt-and-suspenders: the loop above always exits via return or
  // throw, but keep this so the function's contract ("returns a
  // Response or throws") holds even if someone tweaks the loop later.
  throw lastError ?? new Error("fetchWithRetry exhausted without a response");
}

When request validation fails, the error includes field-level details:

{
  "error": {
    "code": "bad_request",
    "message": "Validation failed.",
    "details": {
      "fields": [
        {
          "field": "email",
          "message": "Must be a valid email address."
        },
        {
          "field": "scheduledEnd",
          "message": "Must be after scheduledStart."
        }
      ]
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}