Error handling

A failed API request returns an HTTP error. A successfully queued upload can separately enter the asset error state if processing fails. Handle both paths.

Request errors

HTTP errors normally return:

{
  "code": "asset/not-found",
  "message": "Asset not found",
  "traceId": "..."
}

The SDKs return structured API errors. Handle errors by their code; log the message and details when debugging.

import { CalmLensError } from "@calmlens/sdk";

try {
  await client.assets.retrieve({ assetId });
} catch (error) {
  if (error instanceof CalmLensError && error.code === "asset/not-found") {
    return undefined;
  }
  throw error;
}

Every response, successful or not, carries an X-Request-Id header that identifies the request in CalmLens logs. Log it with failed requests and include it when you contact support.

Retry network failures and server errors with capped exponential backoff. Do not automatically retry validation errors. For a multipart 409, check the expected part number or restart the upload. Retrying the same stale part will fail again.

Retrying requests safely

A request that timed out may have succeeded. Retrying a create or moderate request could then create a second asset that counts toward your usage. To prevent this, send an Idempotency-Key header on POST /projects/:projectId/assets, POST /projects/:projectId/assets/upload, POST /projects/:projectId/assets/multipart-upload and POST /assets/:assetId/part, and send the same key with every retry of that request:

Idempotency-Key: 4f9a1c2e-8b7d-4e61-9a35-0c2b7f1d6e80

• Use a new key for each request. A UUID works well. Keys can be up to 255 printable ASCII characters; anything else returns 400 idempotency/invalid-key.
• A retry returns the saved response. When the first request succeeded, a retry with the same key gets its response for 24 hours, with the header Idempotent-Replayed: true, and nothing runs again.
• The key belongs to one request. Reusing a key for a different request (another path, other query parameters or another body) returns 409 idempotency/key-reused. Raw uploads are compared by their query parameters, Content-Type and Content-Length rather than by their bytes.
• Concurrent retries wait their turn. While the first request is still running, a retry returns 409 idempotency/request-in-progress with a Retry-After header. Wait that many seconds and retry with the same key to receive the result.
• Failures are not saved. If the first request failed, the key is freed and a retry runs the request again, so you can fix the problem and retry with the same key.
• Keys are scoped to your API key. A key sent with one API key never matches a request sent with another.

An externalId is unique within a project, so it also protects against duplicates: a second asset with the same externalId is refused with 409 asset/duplicate-external-id. Unlike an idempotency key, it doesn't return the first response, so retrieve the existing asset instead.

Rate limits

CalmLens does not currently publish a general requests-per-second limit. If a request is throttled, it returns 429 with a Retry-After header giving the number of seconds to wait before retrying. Account upload allowances are enforced separately: exhausting the free upload allowance returns 403 upload/limit-exceeded. File-size and multipart constraints return their documented upload/* errors.

Choose a recovery action

Processing failures

A queued request can succeed while classification later fails. Watch for asset status error through retrieval or events; do not publish that content. Inspect its failure details, correct the input when needed, then retry an eligible asset. See Asset lifecycle.