Errors
Every error is JSON with a message. Some errors also carry a code you can branch on. Some carry
details.
Status codes
Section titled “Status codes”| Status | Meaning | Body |
|---|---|---|
| 400 | Validation failed, or a user input error | { message: "Validation Failed", details: { "body.date": { message, value } } } |
| 401 | No key, an unknown key, or an expired key | { message, code: "UNAUTHENTICATED" } or { message, code: "API_KEY_EXPIRED" } |
| 403 | A valid key without the scope the route needs | { message, code: "INSUFFICIENT_SCOPE" } |
| 403 | A valid key whose organization lacks API access (not enforced yet) | { message, code: "API_ACCESS_REQUIRED" } |
| 403 | The organization has used its storage allowance, on routes that create stored media | { message, code: "STORAGE_QUOTA_EXCEEDED" } |
| 403 | A resource owned by another organization, on most routes | { message, code: "FORBIDDEN" } |
| 404 | Not found, a theme your organization cannot use, or a theme it does not own on a route that changes the theme | { message } |
| 409 | A conflict with the current state: for example a locked graphic, a stale write, a theme, stream input or stream destination still in use, or a stored graphic asset that fails verification | { message, code }; LOCKED also includes holder.userName |
| 410 | A Rive import or source file is no longer available | { message, code } |
| 422 | A Rive graphics request that the graphic cannot apply, for example an unknown reference | { message, code, details? } |
| 429 | The rate limit is exceeded while enforcement is on | { message } |
| 500 | Unexpected. Retry once, then contact support | { message } |
| 503 | An upload or Rive import service is unavailable, or a transfer failed | { message, code } |
For a 500, send the traceparent header value you used to support. It lets LIGR find your request.
Error codes
Section titled “Error codes”code | Status | When | Fix |
|---|---|---|---|
API_KEY_EXPIRED | 401 | The key passed its expiry date | Create a new key in the dashboard |
INSUFFICIENT_SCOPE | 403 | The key lacks the scope the route needs. The message names the scope | Create a key with that scope |
API_ACCESS_REQUIRED | 403 | The key’s organization lacks the api_access entitlement. Not enforced yet | Ask your LIGR contact to enable API access for the organization |
STORAGE_QUOTA_EXCEEDED | 403 | The organization has no storage room for an upload or a stream start | Delete or archive media, or add storage to the subscription |
LOCKED | 409 | Someone has the graphic open in the dashboard editor, or a stale lock has not expired. A lock expires after 60 seconds | Wait, then retry. holder.userName names the editor |
TARGET_CHANGED | 409 | The graphic or theme changed after you read it | Read it again, then retry with the new updatedAt |
GRAPHIC_ASSET_MISSING | 409 | A graphic or theme publish references an S3 asset that is missing | Upload the missing asset, then publish again |
GRAPHIC_ASSET_INVALID | 409 | An asset cannot be read, or its stored size or SHA-256 differs from the recorded value | Replace the asset with the intended bytes, then publish again |
CODE_GRAPHIC_INVALID | 400 | An unknown control variable type, or a bundle that names a file you did not upload in the session it names and the graphic does not already hold | Read details[]. Each line is one problem. Upload the named file, then record the bundle with the uploadSessionId of that upload |
BUNDLE_TOO_LARGE | 400 | The bundle is over 10 MiB, or one file is over 5 MiB | Read details[]. It lists the files that are too large |
THEME_LIMIT_REACHED | 409 | Your organization already owns five themes | Delete a theme you no longer use, or ask your LIGR contact |
THEME_IN_USE | 409 | A competition still uses the theme you want to delete | Read details[]. Remove the theme instance from each competition, then delete again |
IN_USE_BY_STREAM | 409 | A running stream uses the input or destination you want to delete | Read details[]. It names each stream by its id. Stop the stream, then delete again. For a destination, you can also remove it from the stream |
HIGHLIGHT_RULE_AMBIGUOUS | 409 | The competition has two or more highlight rules for the event, saved in the dashboard | Change or remove those rules in the dashboard, then retry. See Make clips |
NO_RECORDING | 409 | A moment asked for a clip, and no recording of the match covers its date | Turn on archiveFullFeed for the stream of the match, upload and sync a video of the match, or send highlight: false. See Make clips |
GRAPHIC_TYPE_MISMATCH | 400 | The id belongs to a Rive graphic, and the route serves code graphics | Use the Rive graphics routes for a Rive graphic |
BAD_USER_INPUT | 400 | The input is invalid. For an upload, the message starts with unsafe asset path when a file name holds .., an empty segment, a control character, or one of ?, #, % | Read message. Fix the input, or rename the file |
RUNTIME_HAS_NO_EDITABLE_SOURCE | 400 | A raw .riv upload requested source retention | Send retainSource: false. The runtime revision preserves those bytes |
INVALID_SELECTION | 400 | The chosen artboard, state machine, or archive entry is unavailable | Read current import metadata, then send an exact returned index or entry |
SCRIPT_SIGNING_UNSUPPORTED | — | A Rive import failed because the file has Rive scripts without a valid Rive signature. The runtime does not run unsigned scripts, and LIGR cannot sign them. The import status carries this code in error.code | Export the .riv from the Rive editor, or build it with rive --publish, then import it |
IMPORT_UNAVAILABLE | 503 | Source import is disabled or not qualified in this environment | Read the capability response and use an available path |
Validation errors
Section titled “Validation errors”A 400 from schema validation names each bad field.
{ "message": "Validation Failed", "details": { "body.date": { "message": "invalid ISO 8601 datetime format, i.e. YYYY-MM-DDTHH:mm:ss", "value": "12-09-2026" } }}Retries
Section titled “Retries”| Status | Retry? |
|---|---|
| 400, 401, 403, 404 | No. Fix the request |
| 409 | For LOCKED or TARGET_CHANGED, retry after resolving the conflict. For GRAPHIC_ASSET_*, repair the asset first. For IN_USE_BY_STREAM, stop the stream first |
| 429 | Yes, after the RateLimit-Reset seconds. See Rate limits |
| 500 | Once. Then contact support |
Make write requests safe to repeat. Read the entity back before you write it again.