Errors

Chronicle returns conventional HTTP status codes and a structured JSON error body on every failure.

Installnpm install @chronicle-labs/sdk

SDK generation in progress - until published, Node 18+ fetch works with no extra dependencies.

The error object

Every error response wraps an error object containing machine-readable type, code, human message, and optional request ID.

Response

JSON

{
  "error": {
    "type": "invalid_request_error",
    "code": "tenant_id_required",
    "message": "tenant_id is required",
    "request_id": "req_01HXYZ"
  }
}

HTTP status codes

200 - Success.
400 - Invalid payload, missing required fields, malformed query params.
401 - Missing or invalid API key / webhook signature.
403 - Authenticated but not permitted.
404 - Resource or source does not exist.
409 - Idempotency key conflict.
429 - Rate limit exceeded.
500 - Unexpected server error.

Retry guidance

Retry 429 and 5xx responses with exponential backoff and jitter. Never retry 4xx validation failures without changing the request. Always include an Idempotency-Key on write operations.

Node

async function withRetries(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (attempt === maxAttempts - 1) throw err;
      const delay = 250 * 2 ** attempt + Math.random() * 200;
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}