Skip to content

Errors

Every error is JSON with a message. Some errors also carry a code you can branch on. Some carry details.

StatusMeaningBody
400Validation failed, or a user input error{ message: "Validation Failed", details: { "body.date": { message, value } } }
401No key, an unknown key, or an expired key{ message, code: "UNAUTHENTICATED" } or { message, code: "API_KEY_EXPIRED" }
403A valid key without the scope the route needs{ message, code: "INSUFFICIENT_SCOPE" }
403A valid key whose organization lacks API access (not enforced yet){ message, code: "API_ACCESS_REQUIRED" }
403The organization has used its storage allowance, on routes that create stored media{ message, code: "STORAGE_QUOTA_EXCEEDED" }
403A resource owned by another organization, on most routes{ message, code: "FORBIDDEN" }
404Not found, a theme your organization cannot use, or a theme it does not own on a route that changes the theme{ message }
409A 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
410A Rive import or source file is no longer available{ message, code }
422A Rive graphics request that the graphic cannot apply, for example an unknown reference{ message, code, details? }
429The rate limit is exceeded while enforcement is on{ message }
500Unexpected. Retry once, then contact support{ message }
503An 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.

codeStatusWhenFix
API_KEY_EXPIRED401The key passed its expiry dateCreate a new key in the dashboard
INSUFFICIENT_SCOPE403The key lacks the scope the route needs. The message names the scopeCreate a key with that scope
API_ACCESS_REQUIRED403The key’s organization lacks the api_access entitlement. Not enforced yetAsk your LIGR contact to enable API access for the organization
STORAGE_QUOTA_EXCEEDED403The organization has no storage room for an upload or a stream startDelete or archive media, or add storage to the subscription
LOCKED409Someone has the graphic open in the dashboard editor, or a stale lock has not expired. A lock expires after 60 secondsWait, then retry. holder.userName names the editor
TARGET_CHANGED409The graphic or theme changed after you read itRead it again, then retry with the new updatedAt
GRAPHIC_ASSET_MISSING409A graphic or theme publish references an S3 asset that is missingUpload the missing asset, then publish again
GRAPHIC_ASSET_INVALID409An asset cannot be read, or its stored size or SHA-256 differs from the recorded valueReplace the asset with the intended bytes, then publish again
CODE_GRAPHIC_INVALID400An 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 holdRead details[]. Each line is one problem. Upload the named file, then record the bundle with the uploadSessionId of that upload
BUNDLE_TOO_LARGE400The bundle is over 10 MiB, or one file is over 5 MiBRead details[]. It lists the files that are too large
THEME_LIMIT_REACHED409Your organization already owns five themesDelete a theme you no longer use, or ask your LIGR contact
THEME_IN_USE409A competition still uses the theme you want to deleteRead details[]. Remove the theme instance from each competition, then delete again
IN_USE_BY_STREAM409A running stream uses the input or destination you want to deleteRead 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_AMBIGUOUS409The competition has two or more highlight rules for the event, saved in the dashboardChange or remove those rules in the dashboard, then retry. See Make clips
NO_RECORDING409A moment asked for a clip, and no recording of the match covers its dateTurn 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_MISMATCH400The id belongs to a Rive graphic, and the route serves code graphicsUse the Rive graphics routes for a Rive graphic
BAD_USER_INPUT400The 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_SOURCE400A raw .riv upload requested source retentionSend retainSource: false. The runtime revision preserves those bytes
INVALID_SELECTION400The chosen artboard, state machine, or archive entry is unavailableRead 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.codeExport the .riv from the Rive editor, or build it with rive --publish, then import it
IMPORT_UNAVAILABLE503Source import is disabled or not qualified in this environmentRead the capability response and use an available path

A 400 from schema validation names each bad field.

400 Bad Request
{
"message": "Validation Failed",
"details": {
"body.date": {
"message": "invalid ISO 8601 datetime format, i.e. YYYY-MM-DDTHH:mm:ss",
"value": "12-09-2026"
}
}
}
StatusRetry?
400, 401, 403, 404No. Fix the request
409For 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
429Yes, after the RateLimit-Reset seconds. See Rate limits
500Once. Then contact support

Make write requests safe to repeat. Read the entity back before you write it again.