Errors & Retries

Every response carries a top-level success boolean. What sits next to it varies by which layer answered, so write your client to read defensively:

• On success, the resource endpoints return data, plus meta on the list endpoints. Some endpoints also spread the payload's own fields alongside data for older consumers — read data and ignore the duplicates.
• On failure, expect message first and fall back to error; both usually carry the same string. Authentication, scope and rate-limit failures also carry a stable code (UNAUTHORIZED, FORBIDDEN, RATE_LIMITED, INTERNAL_ERROR), while a validation message raised by an endpoint may have no code at all. A few older endpoints return error as a nested object rather than a string.

In short: branch on the HTTP status, read code when it is there, and use message ?? error for display.

Success envelope

{
  "success": true,
  "data": {
    "job": { "id": "job_abc123", "...": "..." }
  }
}

The shape of data varies by endpoint. The per-endpoint reference pages document each one.

Error envelope

{
  "success": false,
  "error": "jobNumber is required"
}

Status codes

Recommended retry policy

• 5xx: retry up to 3 times with exponential backoff — 1 s, 2 s, 4 s.
• 429: same pattern; if responses include a Retry-After header, honor it.
• 4xx: do not retry. Fix the payload or the auth, then re-submit.
• Network errors: retry up to 3 times with the same backoff as 5xx.

Reference implementation:

async function retryingRequest(fn, attempt = 0) {
  try {
    return await fn();
  } catch (err) {
    const status = err.response?.status;
    const retryable = !status || status >= 500 || status === 429;
    if (retryable && attempt < 3) {
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, attempt)));
      return retryingRequest(fn, attempt + 1);
    }
    throw err;
  }
}

Common errors

ID fields

const resourceId =
  response.data.data.resource.id ??
  response.data.data.resource.recordId ??
  response.data.data.resource._id;