Error codes
Every error code, its meaning, and the fix.
Every code the video editor reports, what it means, and what to do. Codes are stable names for your code to compare. Messages can change, so do not compare them.
License errors
onLicenseState reports these as state.reason when state.status is blocked. The editor shows the message under License Validation Failed.
| Code | Message | Fix |
|---|---|---|
missing-key | No licence key was given to the editor. Pass your key as the licenseKey prop. | Pass licenseKey. |
malformed | This licence key was not recognised. | Copy the whole key again. It has three parts separated by dots. |
legacy-key | This licence key is in an older format that this editor no longer accepts. Generate a new key at app.layermetry.com/licenses. | Create a new key. |
unknown-key | This licence key was not recognised. | Use a key from app.layermetry.com/licenses. |
bad-signature | This licence key was not recognised. | The key was changed or damaged. Copy it again. |
expired | This licence key expired on 2026-10-04 (the date of expiry). | Renew the license and deploy the new key. |
not-yet-valid | This licence key does not start until 2026-10-04 (the start date), which is in the future. Check this device's date and time. | Correct the device clock. |
wrong-domain | This licence key is not valid for editor.example.com (the host name of the page). | Use a production key for this domain. A development key works only on your own computer. |
revoked | The license server's own sentence. | The license was cancelled or switched off. Contact Layermetry. |
unconfirmed | The editor has not been able to confirm its licence with Layermetry for 30 days (the grace period). Check apiUrl, network rules and your key. | Allow requests to apiUrl in your network and content security policy. |
revoked and unconfirmed show a Try again button. See License validation.
AI errors
Compare AIRequestError.code in your application. Messages can change. Hosted AI is coming soon and available only with an enterprise licence from Layermetry; the published error type retains service license codes.
| Code | Meaning | Retry guidance |
|---|---|---|
not-configured | AI has no usable configuration or available server model. | Configure an available operation before trying again. |
announced | The operation is not available in this release. | Wait for support. |
limit-reached | A session or host request limit was reached. | Retry after the limit is renewed or the input is reduced. |
invalid-input | A request violates the model schema or host restrictions. | Correct the input before trying again. |
no-provider | No provider serves the requested operation. | Configure a provider before trying again. |
transport-failed | A request function failed, an authenticated redirect was refused, or an endpoint returned an unknown failure. | Confirm whether the server accepted the work before resubmitting. |
invalid-response | The response was not readable JSON or its parser failed. | Check the response and server job before resubmitting. |
missing-license-key | The service received no SDK license key. | Correct the service setup before trying again. |
malformed-license-key | The service could not read the SDK license key. | Correct the service setup before trying again. |
invalid-license-key | The service refused the SDK license key. | Correct the service setup before trying again. |
license-unverifiable | The service could not verify the SDK license. | Retry after verification recovers. |
ai-quota-exceeded | The service request quota is exhausted. | Retry after the quota is renewed. |
unsupported-model | The server does not offer the requested model. | Choose an offered model before trying again. |
unsupported-provider | The server does not offer the requested provider. | Correct provider routing before trying again. |
store-unavailable | The server refused work because it could not record usage. | Retry after the usage store recovers. |
unknown-job | A job is absent, expired or inaccessible to this account. | Check the original job and account before starting new work. |
sign-in-required | The service requires a signed-in user. | Sign in before trying again. |
identity-mismatch | The signed-in account differs from the required account. | Use the correct account before trying again. |
identity-unverifiable | The service could not verify the signed-in user. | Retry after identity verification recovers. |
ai-credits-exhausted | The paying account has no AI credits. | Add credits before trying again. |
meter-off | The plan does not include this operation. | Use an eligible plan before trying again. |
invalid-config | A configuration or headers answer is unusable; no request was sent. | Correct configuration before trying again. |
invalid-output | A readable response is not a usable result for this operation. | Correct the response; another generation may incur a charge. |
auth-refused | The endpoint returned HTTP 401 or 403 without a known SDK code. | Correct authentication before trying again. |
rate-limited | The endpoint returned HTTP 429 without a known SDK code. | Retry after backoff when the server rejected submission. |
timeout | The configured submission timeout elapsed. | Check server acceptance before resubmitting. |
cancelled | The editor or user stopped the request. | Check whether accepted work is still running. |
outcome-unknown | A network failure left submission acceptance unknown. | Check the server before resubmitting. |
Provider errors
providerError preserves the server’s error alongside the SDK code.
| Field | Type | Description |
|---|---|---|
code | Optional string | The provider’s code, including codes the SDK does not recognize. |
message | Optional string | The provider’s plain-text explanation, limited to 500 characters. |
status | Optional number | The HTTP response status. |
requestId | Optional string | The request identifier from response headers or the body. |
Codes and request IDs are limited to 100 characters. Control characters are removed. Request IDs are read from x-request-id, x-correlation-id, or requestId in the body. Unknown provider codes do not replace the SDK’s code. Provider messages can repeat user content; avoid logging them when you only need a request ID.
Retry safety
A confirmed refusal can be retried after its cause is corrected. A response parsing failure does not prove generation was refused. outcome-unknown, timeout and cancellation during submission do not establish whether work was accepted or billed. Check server records before repeating those requests.
Automatic submission retries require an idempotency contract. They apply only to thrown network requests and HTTP 429, 502, 503 or 504. The server must recognize the reused key. See Retries.
errorMessages changes user-facing wording by category. onGenerationError receives the SDK error and attempt context. See Generation events.
Top-up address
With ai-credits-exhausted and meter-off, your server can send topUpUrl, the address where the account buys more credits. AIRequestError carries it as error.topUpUrl. The editor keeps only an http or https address, and it shows no link itself. You decide whether your users see a way to pay.
{ "ok": false, "error": { "code": "ai-credits-exhausted", "message": "This workspace has no AI credits left.", "topUpUrl": "https://app.example.com/billing" } }Your AI server sends a code with { "ok": false, "error": { "code": "…", "message": "…" } }. See Custom AI endpoint.
Export errors
When an option of the Export panel cannot run in this browser, the panel greys it out, and its tooltip explains why:
| Reason | Message |
|---|---|
api-missing | This browser is missing the video features that export needs. |
decoder-unsupported | One of your clips uses a format this browser cannot decode for export. |
encoder-unsupported | This browser on this device has no encoder for that option at this size. |
audio-encoder-unsupported | This browser build cannot encode audio for export, so this option is unavailable. |
offscreen-canvas-unavailable | This browser cannot render frames off-screen, which this option needs. |
odd-dimensions | The width or height is an odd number, which H.264 cannot save. Export will offer a size one pixel smaller, or the HEVC option keeps the exact size. |
unsupported-container | One of your clips is in a container this export path cannot read. |
empty-timeline | There is nothing on the timeline to export yet. |
codec-not-implemented | This format is not available for export yet. |
storage-unavailable | This export is too large to hold in memory, and this browser cannot stream it to disk. Try a shorter timeline or a lower bitrate. |
probe-error | This browser could not answer whether it supports that option, so it is unavailable. |
When a whole export cannot run, the export list shows a failed row with a longer sentence for the same code, and onExportProgress receives a last event with done: true and that sentence as error. Export failures lists every sentence. An export that fails while it runs, after the editor has closed, also ends with such an event. See Events.
Thumbnail errors
generateThumbnail and onThumbnails report a missing picture with reason, a sentence, and reasonCode:
reasonCode | Meaning |
|---|---|
unsupported-container | AVI, Windows Media, or MPEG streams. Browsers cannot decode what is inside them. |
unreadable-file | Not a picture or video format that the editor reads, or its index is damaged. |
no-video-track | A sound file, or a video file with no pictures. |
no-decoder | This browser cannot decode video from scripts. The file is fine. |
unsupported-codec | The browser's decoder refused this kind of video. |
decode-failed | The decoder accepted the video and produced nothing usable. |
image-undecodable | The browser refused the picture, for example HEIC on Chrome. |
timeout | The time limit passed first. |
cancelled | Your signal was aborted. |
encode-failed | A picture was decoded but could not be written as an image file. |