Skip to content

API Error Codes ​

Look up HTTP status codes, structured errors, Agent task errors, and embedded AI stream errors.

HTTP status codes ​

Failed HTTP API requests return success: false. For a string or validation object, use the HTTP status and message.

StatusMeaning
400Invalid request format or fields, such as JSON, form data, query parameters, project content, or a master template.
401Missing or malformed Bearer credentials, or an invalid or inactive API key.
402Insufficient credits or an embedded AI request that failed the credit eligibility check.
403No credit account is bound, or the account is unavailable.
404The task or embedded AI run is missing, has an invalid ID, or is outside the current API key scope. Task creation can also return this status if the created record cannot be reloaded.
409The same x-request-id is in progress, or a state or credit update conflicts.
422The request was parsed, but the canvas, view, dimensions, or primitives cannot be rendered as requested.
4993D rendering was cancelled. A disconnected client may receive no response.
500The service failed to process the request. An out-of-range slideIndex also returns this status for legacy PNG, SVG, and TikZ.
502An unrecognized response was returned.
503The 3D render queue is full.
504The 3D render deadline was exceeded, including time spent waiting in the queue.

Authorization and billing codes ​

These are the HTTP mappings for authorization and billing errors. Some paths return a message string only.

Code / HTTPMeaning
INVALID_INPUT / 400Authorization or billing input failed validation.
UNAUTHENTICATED / 401The authorization service could not verify the API key.
INSUFFICIENT_CREDITS / 402Insufficient credits.
ACCOUNT_NOT_FOUND / 403The authorization or billing service could not find the credit account.
INVALID_STATE / 409The current state does not allow the operation.
CAS_CONFLICT / 409Concurrent credit updates conflicted and internal retries were exhausted.
CONFLICT / 409An authorization or billing operation conflicted.

Render error codes ​

Read the render error code from error.code.

Code / HTTPMeaning
UNSUPPORTED_3D_GEOMETRY / 422Legacy PNG, SVG, and TikZ require an entirely 2D project. A 2D target canvas in PNG v2 also cannot contain 3D primitives.
RENDER_INVALID_REQUEST / 422The target canvas is invalid, the view and canvas dimensions differ, the bounds, camera, or crop are invalid, or either physical PNG dimension exceeds 2048 pixels.
UNSUPPORTED_3D_PRIMITIVE / 422The 3D canvas contains a primitive the renderer does not support.
RENDER_CANCELLED / 499Cancelled after a client disconnect or render worker pool shutdown. Start a new request if the connection is available and the export is still needed.
RENDER_WORKER_FAILED / 500The render failed or the worker exited or shut down. Check retryable in the response.
RENDER_QUEUE_FULL / 503The 3D render queue is full. Retry after the number of seconds in the Retry-After header.
RENDER_TIMEOUT / 5043D rendering exceeded the deadline, including time spent in the queue. The request can be retried.

Agent task error codes ​

The task list and detail APIs return failed tasks with HTTP 200. When a task has status: "error", read its extra.errorCode and extra.errorMessage.

CodeMeaning
input_image_fetch_failedThe task could not retrieve an input image.
artifact_upload_not_configuredProject artifact upload is unavailable because the service configuration is missing.
invalid_ai_environmentThe server-side AI environment is invalid or missing configuration.
agent_execution_failedThe Agent failed to execute the task.

Embedded AI stream error codes ​

Once HTTP 200 opens the stream, read code and error from the JSON payload of a local terminal SSE error event. Stream relay or read failures may only carry a message. Upstream response.failed and error events use the provider’s own payload format.

CodeMeaning
invalid_ai_environmentThe server-side AI environment is invalid or missing configuration.
unsupported_embedded_ai_modelThe model used for the streaming run is unsupported.
embedded_ai_execution_failedThe embedded AI run failed.