Error codes

The image editor reports two kinds of error codes: license codes, when the license check stops the editor, and AI codes, when an AI request fails. The reason codes are stable names. The sentences may change between versions.

License errorsCopy Anchor Link

When the license check stops the editor, onLicenseState reports state.status: 'blocked' with one of these reason codes, and the screen shows the message.

The screens for revoked and unconfirmed have a Try again button, which asks the license server again at once.

AI errorsCopy Anchor Link

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.

Provider errorsCopy Anchor Link

providerError preserves the server’s error alongside the SDK code.

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 safetyCopy Anchor Link

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 addressCopy Anchor Link

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.

{ "error": { "code": "ai-credits-exhausted", "message": "This workspace has no AI credits left.", "topUpUrl": "https://app.example.com/billing" } }

In your own codeCopy Anchor Link

The package exports AIRequestError and describeAIError, to show the same titles in your own interface:

import { AIRequestError, describeAIError } from '@layermetry/media-editor/react';

const error = new AIRequestError('limit-reached', 'You have made 20 pictures today. Try again tomorrow.', 429);
const { title, description } = describeAIError(error);
console.log(`${title}: ${description}`);
// Generation limit reached: You have made 20 pictures today. Try again tomorrow.