Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt

Use this file to discover all available pages before exploring further.

Blaxel returns structured error responses in case of request failure. These error responses include additional information designed for coding agents and LLMs. Every error has a consistent JSON body and response header, as shown below: 
{
  "error": {
    "action": "Stop. URL does not match a Blaxel route. Use `https://{sbx|agt|mcp|mdl|job}-{name}-{workspace}.{region}.bl.run[/{path}]` for workloads or `https://{preview_id}.preview.bl.run/{path}` for previews. Get the canonical URL from the SDK (e.g. `sandbox.metadata.url`), not by hand.",
    "code": "ROUTE_NOT_FOUND",
    "do_not": "Do not retry, do not guess URLs, do not use `run.blaxel.ai` (not served).",
    "docs_url": "https://docs.blaxel.ai/Sandboxes/Ports.md",
    "message": "Preview not found: xxx",
    "origin": "platform",
    "retryable": false,
    "status": 404,
    "timestamp": "2026-04-23T14:49:43+00:00"
  }
}
FieldDescription
error.actionAgent-readable actions to be taken
error.codeMachine-readable error code
error.do_notAgent-readable actions not to be taken
error.docs_urlDocumentation related to this error
error.messageHuman-readable description
error.origin"platform" when emitted by Blaxel; otherwise absent
error.retryableWhether the request can return a different response if it is retried
error.statusHTTP status code (same as HTTP response header)
error.timestampTimestamp in ISO-8601 format

​
Error codes

CodeHTTPRetryableWhen emitted
ROUTE_NOT_FOUND404NoRequest path couldn’t be parsed into a known workload, preview, or sandbox subdomain shape
WORKLOAD_NOT_FOUND404NoWorkload record doesn’t exist
WORKSPACE_NOT_FOUND404NoWorkspace couldn’t be resolved for a deployment-subdomain request
WORKLOAD_UNAVAILABLE404YesWorkload exists but no healthy replica is currently serving it
AUTHENTICATION_REQUIRED401NoCredentials missing
AUTHENTICATION_FAILED401NoCredentials present but invalid or rejected
FORBIDDEN403NoAuthenticated but not authorized
BAD_REQUEST400NoMalformed request
USAGE_LIMIT_EXCEEDED402NoPlan quota reached
POLICY_VIOLATIONvariesNoPolicy rule rejection
Last modified on April 24, 2026