Errors

Every endpoint fails the same way: a non-2xx status and a JSON body with one error object. Branch on code, which is stable; show message to people, which is written to be read.

Error shape#

{
  "error": {
    "code": "insufficient_credits",
    "message": "This needs 80 credits and you have 35. Presets, recolors, and exports stay free.",
    "details": { "needed": 80, "balance": 35 }
  }
}

details is null unless there is something structured to add. For a body that fails validation it is an array of "path: message" strings, one per problem:

{
  "error": {
    "code": "invalid_request",
    "message": "Request body is invalid.",
    "details": ["prompt: Too small: expected string to have >=3 characters"]
  }
}

Spec, clip and canvas validation use the same field: "Spec is invalid.", "Clip is invalid." or "Canvas graph is invalid." with every problem listed in details.

Status codes#

Error codes#

Failed jobs#

A job that starts fine can still fail later. That isn't an HTTP error: the job reaches status: "failed" (or "canceled") with a human-readable error string, and your webhook receives job.failed or job.canceled.

{
  "id": "job_…",
  "object": "job",
  "type": "generate",
  "status": "failed",
  "error": "Cost ceiling of $0.56 reached",
  "cost_usd": 0.5612,
  "result": null
}

• Credits come back. Credits are held when a job starts and refunded automatically when it fails or is canceled.
• Cost ceiling. A job whose model spend passes its ceiling is stopped with Cost ceiling of $… reached. See Holds, refunds and ceilings.
• Server restarts. A job interrupted by a restart fails with Interrupted by a server restart. Retry the request.
• Model errors are surfaced as AI service error: ….
• A failed creation leaves the mascot with status: "failed" and the reason in mascot.error. A failed edit keeps the previous version current.

Handling errors in the SDK#

The SDK throws LumorigError with status, code, message and details copied from the body. It adds three codes of its own:

Example#

import { LumorigError } from "@lumorig/sdk";

async function withRetry<T>(fn: () => Promise<T>, tries = 3): Promise<T> {
  for (let i = 0; ; i++) {
    try {
      return await fn();
    } catch (err) {
      const retryable = err instanceof LumorigError && (err.status >= 500 || err.code === "not_ready");
      if (!retryable || i === tries - 1) throw err;
      await new Promise((r) => setTimeout(r, 1000 * 2 ** i));
    }
  }
}

• Credits & limitsPrices, refunds and the limits behind 400s.
• REST API referenceWhich endpoints return which status.