> ## Documentation Index > Fetch the complete documentation index at: https://docs.beta.b3os.org/llms.txt > Use this file to discover all available pages before exploring further. # Errors All 151 B3OS error codes with HTTP status, meaning, retry advice and the Firecrawl mapping, generated from errors.yaml. Every B3OS error has a stable `code`. Native endpoints return it in an RFC 9457 problem with the content type `application/problem+json`: ```json { "type": "https://docs.beta.b3os.org/errors#rate_limited", "title": "Rate limited", "status": 429, "code": "rate_limited", "detail": "60 scrapes per minute allowed; retry in 12 seconds", "instance": "req_01m5t4yg394wegr3j4y01qb363", "retry_after_s": 12, "limit": { "id": "vision.scrape.rpm", "limit": 60, "unit": "requests", "window_s": 60, "current": 60 } } ``` `type` links to the code's entry on this page (`https://docs.beta.b3os.org/errors#`). `instance` is the request ID, the same value as the `x-request-id` header; [`GET /v1/requests/{request_id}`](/platform/requests) returns the request's record. `detail` explains this occurrence and may change between releases, so branch on `code`, never on `detail`. **Retryable** codes can succeed later with the same request: wait `Retry-After` seconds when the header is present. Codes marked not retryable need a change to the request, the account or the object first. Some codes add members to the problem: | Member | Meaning | |---|---| | `errors` | One item per invalid field: `pointer` (a JSON pointer such as `/url`, or `#query/`, `#path/`, `#header/`) and `detail`. | | `reason` | A finer cause, for codes that document one. | | `required_scope` | The scope the credential lacks. | | `retry_after_s` | The `Retry-After` value, for clients that read only the body. | | `limit` | The limit that was hit: `id`, `limit`, `unit`, and `window_s` or `current` when they apply. IDs match `GET /v1/limits`. | | `current_status` | The object's status, for state conflicts. | | `upstream_status` | The HTTP status an upstream returned. | | `step` | The step that failed: a routine step ID, an `act` index or a render path such as `beats/2/do/0`. | | `pack_error` | The error a pack's error mapping chose. | Compatibility paths keep their upstream error shapes: `/v1/infer/*` answers in the OpenAI shape with the B3OS code in `error.code`, `/compat/firecrawl/*` answers in the Firecrawl shape listed with each code below, and the device-login endpoints answer in the OAuth shape. See [Errors in the API overview](/api/overview) for how each surface reports them. ## Request shape invalid_request `400` · Invalid request · Not retryable · Members: `errors` · Firecrawl: `400` `BAD_REQUEST` "Bad Request" The request body, query string, path or headers failed validation, or the body is not valid JSON. `errors[]` lists each problem: `pointer` is a JSON pointer into the body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters (for example `#query/limit`). Fix the request before retrying. invalid_url `400` · Invalid URL · Not retryable · Members: `errors` · Firecrawl: `400` `invalid_url` "Invalid URL" A URL you supplied (a page to scrape, a webhook, an action endpoint) does not parse, is not absolute, or uses a scheme other than `http` or `https`. The `errors[]` pointer names the field. unsupported_media_type `415` · Unsupported media type · Not retryable · Firecrawl: `415` `unsupported_media_type` "Unsupported Media Type" The `Content-Type` is not accepted by this operation. Most operations take `application/json`; file uploads take `application/octet-stream`. not_acceptable `406` · Not acceptable · Not retryable The `Accept` header asks for a representation this operation cannot produce. Operations that stream accept `text/event-stream`; everything else returns `application/json` unless documented otherwise. payload_too_large `413` · Payload too large · Not retryable · Firecrawl: `413` `payload_too_large` "Payload Too Large" The request body is larger than this operation accepts (`x-b3os-max-body` in the OpenAPI spec). Send less data per request, or use the file and batch endpoints for bulk data. route_not_found `404` · Route not found · Not retryable · Firecrawl: `404` `route_not_found` "Not Found" No operation exists at this method and path. Check the path against the API reference. method_not_allowed `405` · Method not allowed · Not retryable · Firecrawl: `405` `method_not_allowed` "Method Not Allowed" The path exists but does not accept this HTTP method. The `Allow` header lists the methods it accepts. edge_only `421` · Served by beta-api.b3os.org · Not retryable This operation is served by beta-api.b3os.org, not by the node you called; call it there with an API key. Inside a B3OS sandbox, `http://127.0.0.1:7700` reaches the node products directly, but account operations (keys, usage, limits, organizations, projects, sign-in, the pack registry) exist only at `https://beta-api.b3os.org`. `dist/routes.json` marks them `served_by: edge`. limit_exceeded `422` · Limit exceeded · Not retryable · Members: `limit` · Firecrawl: `422` `limit_exceeded` "Limit exceeded" A parameter asks for more than your plan allows, for example `vcpu: 4` when sandboxes allow 2, or a crawl `limit` above 500. The `limit` member names the limit and its value. Lower the value; `GET /v1/limits` lists every limit that applies to you. idempotency_key_invalid `400` · Invalid idempotency key · Not retryable · Firecrawl: `400` `idempotency_key_invalid` "Invalid idempotency key" The `Idempotency-Key` header is empty, longer than 255 characters, or contains characters outside printable ASCII. idempotency_key_conflict `409` · Idempotency key conflict · Not retryable · Firecrawl: `409` `idempotency_key_conflict` "Idempotency key already used for a different request" This `Idempotency-Key` was already used in the last 24 hours with a different method, path or body, or by a different API key in the same project. Use a new key for a new request. idempotency_request_in_progress `409` · Request in progress · Retryable · Members: `retry_after_s` · Firecrawl: `409` `idempotency_request_in_progress` "A request with this idempotency key is in progress" A request with this `Idempotency-Key` is still being processed. Retry after `Retry-After` seconds to receive the stored response. conflict `409` · Conflict · Not retryable · Members: `current_status` The object's current state does not allow this operation. The `current_status` member, when present, shows the state. Fetch the object and reconcile before retrying. resource_not_found `404` · Not found · Not retryable The object does not exist or belongs to another project. B3OS returns 404 (never 403) for objects outside your project so that IDs do not leak across tenants. Product-specific codes such as `sandbox_not_found` are used where they exist. not_implemented `501` · Not implemented · Not retryable · Firecrawl: `501` `not_implemented` "Not Implemented" The operation is part of the published contract but is not available on this deployment yet (operations marked `x-b3os-stage: stretch`). The detail names the alternative when there is one. ## Authentication and authorization unauthorized `401` · Unauthorized · Not retryable · Members: `reason` · Firecrawl: `401` `unauthorized` "Unauthorized" The request has no usable credentials. The `reason` member says why: `missing` (no `Authorization` header; send `Bearer ` with a `b3os_sk_` key or a `b3os_pat_` token from `b3os login`), `malformed` (wrong prefix or checksum; check the whole value was copied), `unknown`, `expired`, `revoked`, `replayed` or `wrong_node` (node tokens only), or `ticket` (a stream ticket that is unknown, older than 30 seconds, already used, or bound to another resource). Inside a B3OS sandbox, call `http://127.0.0.1:7700` with no key instead. forbidden `403` · Forbidden · Not retryable · Members: `reason`, `required_scope` · Firecrawl: `403` `forbidden` "Forbidden" The caller is authenticated but not allowed to do this. The `reason` member says why: `scope` (the key lacks the scope in `required_scope`, for example `sandboxes:write`; create a key with it or grant it to the sandbox in `api.scopes`), `scope_escalation` (a new key, token or sandbox grant asks for scopes or a spend cap beyond the caller's own), `role` (your organization role does not allow it), `session_required` (the operation only accepts a signed-in dashboard session), or `csrf` (a cookie-authenticated write without a valid `x-b3os-csrf` header; fetch `GET /v1/auth/session` for a new `csrf_token`). ticket_limit `429` · Too many stream tickets · Retryable · Members: `retry_after_s` The node holds too many unredeemed stream tickets. Tickets expire after 30 seconds; request one only when you are about to open the stream, and retry after `Retry-After` seconds. auth_unavailable `503` · Authentication temporarily unavailable · Retryable · Members: `retry_after_s` · Firecrawl: `503` `auth_unavailable` "Service Unavailable" The node cannot verify tokens right now (its replay cache is full or its verification keys are rotating). Retry after `Retry-After` seconds. signed_url_invalid `403` · Invalid or expired signed URL · Not retryable · Members: `reason` A `usercontent.b3os.org` link was refused: a render artifact URL (`node`, `exp`, `sig`) or a sandbox port preview token (`/sbx////`). The `reason` member is `missing` (no signature or token), `malformed`, `expired` (past `exp`), `signature` (it does not verify, for example because the URL was changed) or `wrong_node`. Get a fresh link: `GET /v1/render/artifacts/{artifact_id}` or `POST /v1/sandboxes/{sandbox_id}/ports/{port}/url`. ## Limits and billing rate_limited `429` · Rate limited · Retryable · Members: `retry_after_s`, `limit` · Firecrawl: `429` `rate_limited` "Rate limit exceeded" Too many requests in the current window. Wait `Retry-After` seconds; the `RateLimit-*` headers and the `limit` member show which limit applies (for example `vision.scrape.rpm`). The device-login endpoints (`POST /v1/auth/device/code`, `POST /v1/auth/device/token`) return it in the OAuth error shape (`{"error": "rate_limited", "error_description": ...}`) when one address starts or polls too many logins; polling faster than the device code's `interval` is `slow_down` (400) instead. concurrency_limited `429` · Concurrency limit reached · Retryable · Members: `retry_after_s`, `limit` · Firecrawl: `429` `concurrency_limited` "Concurrency limit reached" You already have the maximum number of concurrent operations of this kind (for example 10 running sandboxes or 5 browser sessions). Wait for one to finish, or stop one you no longer need. quota_exceeded `429` · Quota exceeded · Retryable · Members: `retry_after_s`, `limit` · Firecrawl: `429` `quota_exceeded` "Quota exceeded" A daily or monthly quota is used up (for example 50,000 routine steps per day, or the per-organization egress budget). `Retry-After` is the number of seconds until the quota resets. credits_exhausted `402` · Credits exhausted · Not retryable · Firecrawl: `402` `credits_exhausted` "Insufficient credits" Your organization has no credits left. Requests fail until credits are added; the dashboard shows the balance. spend_cap_exceeded `402` · Key spend cap reached · Not retryable · Firecrawl: `402` `spend_cap_exceeded` "Key spend cap reached" This API key reached its spend cap. Raise the cap with `PATCH /v1/keys/{key_id}` or use another key. Other keys in the organization are not affected. ## Egress and upstreams egress_denied `403` · Destination not allowed · Not retryable · Members: `reason` · Firecrawl: `403` `egress_denied` "Destination not allowed" The egress guard refused the destination: a scheme other than http/https, or an address that is loopback, private (10/8, 172.16/12, 192.168/16), CGNAT or tailnet (100.64/10), link-local or metadata (169.254/16), benchmark (198.18/15), unique-local or link-local IPv6, multicast, or the node's own address; a redirect hop that lands on one of those; or a host or port outside a sandbox or pack allowlist. The `reason` member is one of `scheme`, `loopback`, `private_address`, `tailnet`, `link_local`, `metadata`, `multicast`, `node_address`, `not_allowlisted`. upstream_error `502` · Upstream error · Not retryable · Members: `upstream_status`, `pack_error` · Firecrawl: `502` `upstream_error` "Bad Gateway" The third-party server answered with an error or a response B3OS could not use. `upstream_status` carries its HTTP status; for pack actions, `pack_error` carries the error the pack's error mapping chose. Whether a retry helps depends on the upstream (`pack_error.retryable` when present); B3OS retries only read-only calls itself. upstream_unreachable `502` · Upstream unreachable · Retryable · Members: `reason` · Firecrawl: `502` `upstream_unreachable` "Bad Gateway" B3OS could not reach the destination: DNS resolution failed, the connection was refused or reset, or the TLS handshake failed. The `reason` member is `dns`, `connect` or `tls`. upstream_timeout `504` · Upstream timeout · Retryable · Firecrawl: `504` `upstream_timeout` "Gateway Timeout" The destination did not respond within the operation's timeout. Retry later or raise `timeout_ms` where the operation has one. upstream_too_large `502` · Upstream response too large · Not retryable · Firecrawl: `502` `upstream_too_large` "Upstream response too large" The destination's response exceeded the size cap for this operation, so B3OS stopped reading it. too_many_redirects `502` · Too many redirects · Not retryable · Firecrawl: `502` `too_many_redirects` "Too many redirects" The destination redirected more than 10 times. Each hop is checked by the egress guard; a hop to a refused address returns `egress_denied` instead. cap_invalid `407` · Egress capability invalid · Not retryable A request on b3osd's egress capability socket (the actions-js sidecar's way out, packages/spec/sidecars/ actions-js.md §5) carried no `Proxy-Authorization: Bearer `, or a token that is unknown, expired or revoked. Tokens are issued per action invocation and end with it; start a new invocation. ## Availability node_unavailable `503` · Node unavailable · Retryable · Members: `retry_after_s` · Firecrawl: `503` `node_unavailable` "Service Unavailable" The B3OS node that serves this product is unreachable from the edge (restart or network). Retry after `Retry-After` seconds. Inbound routine webhooks are queued durably and replayed in order when the node returns. product_unavailable `503` · Product unavailable · Retryable · Members: `retry_after_s` · Firecrawl: `503` `product_unavailable` "Service Unavailable" The node is up but this product is not ready, for example while its browser pool or a sidecar restarts. `/readyz` and the status page show per-product readiness. capacity_unavailable `503` · No capacity available · Retryable · Members: `retry_after_s` · Firecrawl: `503` `capacity_unavailable` "Service Unavailable" No warm capacity is free and the wait queue is full (sandbox slots, browsers, capture workers). This is node-wide, not your plan limit. Retry after `Retry-After` seconds. budgets_unavailable `503` · Budgets unavailable · Retryable · Members: `retry_after_s` · Firecrawl: `503` `budgets_unavailable` "Service Unavailable" The node could not refresh its budget snapshot from beta-api.b3os.org recently, so it cannot check your credits and caps and does not start metered work (scrapes, renders, sandboxes, routine steps, action calls, inference) until it can. Requests that cost nothing still work. Retry after `Retry-After` seconds. request_timeout `504` · Request timeout · Retryable · Firecrawl: `504` `request_timeout` "Gateway Timeout" The operation did not finish within its time limit (`x-b3os-timeout-ms`). A handler works on a request for at most 60 seconds; `x-b3os-timeout-ms` allows up to 65,000 ms end to end, the extra 5 seconds covering queueing and the edge, which keeps every request under Cloudflare's 100-second origin limit. For long work, create a job and use `?wait=`, the events stream or a webhook. invoke_depth_exceeded `508` · Call depth exceeded · Not retryable A product called another product in-process more than the allowed nesting depth (for example a routine whose steps call routines that call it back). Break the cycle in your routine or action composition. internal `500` · Internal error · Retryable · Firecrawl: `500` `internal` "Internal Server Error" Something failed inside B3OS. Retrying with backoff usually works. If it persists, contact support with the `instance` value (the request ID). ## Jobs job_not_found `404` · Job not found · Not retryable · Firecrawl: `404` `job_not_found` "Extract job not found" No job with this `job_` ID exists in your project, or its record has expired. job_already_finished `409` · Job already finished · Not retryable · Members: `current_status` · Firecrawl: `409` `job_already_finished` "Job already finished" The job (or routine run) already reached a terminal status, so it cannot be canceled or signaled. The `current_status` member shows `succeeded`, `failed` or `canceled`. job_canceled `409` · Job canceled · Not retryable Used as the `error` of a job that was canceled before it finished. Partial results, if any, stay on the job. job_timed_out `504` · Job timed out · Retryable Used as the `error` of a job that ran past its time budget. Retry with a smaller workload or a larger budget where one is configurable. job_expired `410` · Job results expired · Not retryable · Firecrawl: `404` `job_expired` "Job expired" The job finished, but its results were deleted at the end of the retention period (see the job's `expires_at`). stream_resume_unavailable `410` · Stream position expired · Not retryable `Last-Event-ID` points at events that are no longer retained. Reconnect without `Last-Event-ID` and read the current state from the job object. invalid_webhook_url `422` · Invalid webhook URL · Not retryable · Firecrawl: `400` `invalid_webhook_url` "Invalid webhook URL" The `webhook.url` is not an absolute `https://` URL, is longer than 2,048 characters, or resolves to an address the egress guard refuses. ## Platform api_key_not_found `404` · API key not found · Not retryable No API key with this ID exists in your organization. project_not_found `404` · Project not found · Not retryable No project with this ID exists in your organization. org_not_found `404` · Organization not found · Not retryable No organization with this ID exists, or you are not a member of it. request_not_found `404` · Request not found · Not retryable No request with this ID exists in your project. Request records are kept for 7 days. project_not_empty `409` · Project not empty · Not retryable The project still has running sandboxes, open browser sessions or active routines. Stop or delete them, then delete the project. last_project `409` · Last project · Not retryable An organization must keep at least one project. Create another project before deleting this one. invite_code_invalid `400` · Invalid invite code · Not retryable The invite code is unknown or expired. Beta access is by invite; check the code you were sent. invite_code_used `409` · Invite code already used · Not retryable The invite code was already redeemed. Each code creates one organization. email_code_invalid `400` · Invalid email code · Not retryable The sign-in code is wrong or expired (codes are valid for 10 minutes). Request a new code. user_code_not_found `404` · Device code not found · Not retryable The device login code is unknown or expired. Run `b3os login` again for a new code. device_authorization_finished `409` · Device login already decided · Not retryable This device login was already approved or denied. publisher_not_allowed `403` · Publisher not allowed · Not retryable In the beta, only first-party publishers (`io.b3os`) can publish packs to the registry. pack_version_exists `409` · Pack version exists · Not retryable This pack version is already published. Versions are immutable; publish a higher semver version. pack_invalid `422` · Invalid pack · Not retryable · Members: `errors` The pack manifest failed `b3pack.schema.json` validation or publish-time compilation. `errors[]` points into the manifest. pack_signature_invalid `422` · Invalid pack signature · Not retryable The publisher signature does not verify against the uploaded manifest and bundle hashes, or the signing key is not registered to the publisher. org_suspended `403` · Organization suspended · Not retryable The organization is suspended, so its keys, tokens and dashboard sessions cannot start work. Account operations that read the organization still answer. Contact support. hook_queue_full `503` · Webhook queue full · Retryable · Members: `retry_after_s` The node is unreachable and this hook already holds the most deliveries the edge queues for one hook (10,000, or 72 hours of them). The delivery was not stored; retry after `Retry-After` seconds, as webhook providers do. ## Device login The device-login endpoints (`POST /v1/auth/device/code`, `POST /v1/auth/device/token`) answer with the OAuth error shape `{"error": "", "error_description": "…"}` (RFC 6749 section 5.2, RFC 8628 section 3.5) instead of a problem. authorization_pending `400` · Authorization pending · Retryable The user has not approved the device login yet. Keep polling at the `interval` from the device code response. slow_down `400` · Slow down · Retryable The client polled the token endpoint faster than the device code's `interval`. Add 5 seconds to the polling interval, as RFC 8628 requires. Too many logins from one address get `rate_limited` (429) instead. access_denied `400` · Access denied · Not retryable The user denied the device login. Stop polling. expired_token `400` · Device code expired · Not retryable The device code expired before approval. Start a new login. invalid_grant `400` · Invalid grant · Not retryable The device code is unknown or was already exchanged for a token. invalid_client `401` · Invalid client · Not retryable The `client_id` is not a registered B3OS client (`b3os-cli`, `b3os-mcp`, `b3os-sdk`). unsupported_grant_type `400` · Unsupported grant type · Not retryable The token endpoint only accepts `grant_type=urn:ietf:params:oauth:grant-type:device_code`. ## Vision session_not_found `404` · Browser session not found · Not retryable No browser session with this `brs_` ID exists in your project. session_closed `409` · Browser session closed · Not retryable · Members: `current_status` The session was closed or reached its timeout, and its browser was destroyed. Create a new session; save cookies and storage to a profile first if you need them again. profile_not_found `404` · Browser profile not found · Not retryable · Firecrawl: `404` `profile_not_found` "Profile not found" No browser profile with this ID or name exists in your project. Profiles never cross organizations. profile_domain_mismatch `422` · Profile domain mismatch · Not retryable · Members: `errors` · Firecrawl: `422` `profile_domain_mismatch` "Profile domain mismatch" A cookie domain or origin host in the uploaded or saved storage state is not one of the profile's `domains` (or a subdomain of one). Add the domain to `domains`, or remove the state for it. profile_conflict `409` · Profile changed since it was loaded · Not retryable · Members: `current_status` · Firecrawl: `409` `profile_conflict` "Profile changed since it was loaded" The session loaded an older `revision` of the profile than the current one, so saving back would discard newer state. Save with `overwrite_profile: true` to replace it anyway, or reload the profile in a new session. profile_name_taken `409` · Profile name taken · Not retryable Another profile in this project already uses this name. Names are unique per project. crawl_not_found `404` · Crawl not found · Not retryable · Firecrawl: `404` `crawl_not_found` "Crawl job not found" No crawl with this `crawl_` ID exists in your project, or it expired. batch_not_found `404` · Batch scrape not found · Not retryable · Firecrawl: `404` `batch_not_found` "Batch scrape job not found" No batch scrape with this `batch_` ID exists in your project, or it expired. robots_disallowed `403` · Disallowed by robots.txt · Not retryable · Firecrawl: `403` `robots_disallowed` "Disallowed by robots.txt" The site's robots.txt or Content Signals disallow fetching this URL for this purpose. Vision honors them by default and the beta does not offer an override. content_type_unsupported `422` · Content type not supported · Not retryable · Members: `reason` · Firecrawl: `422` `content_type_unsupported` "Unsupported content type" The URL returned a content type vision cannot convert to the requested formats (for example video or a binary archive). The `reason` member carries the content type. navigation_failed `502` · Navigation failed · Retryable · Members: `reason` · Firecrawl: `502` `navigation_failed` "Bad Gateway" The browser could not load the page (a `net::ERR_*` failure, a crash, or an aborted navigation). The `reason` member carries the browser's error string. scrape_timeout `504` · Scrape timed out · Retryable · Firecrawl: `408` `SCRAPE_TIMEOUT` "Request Timeout" The page did not finish loading and converting within `timeout_ms`. Retry with a larger timeout, or use `engine: "fetch"` for pages that do not need JavaScript. target_not_found `422` · Target not found · Not retryable · Members: `step` · Firecrawl: `422` `target_not_found` "Action target not found" No element matched the action's target (CSS `selector`, visible `text`, or `role` plus accessible `name`) within the wait time, or the element stayed outside the viewport after scrolling it into view. Used by browser actions (`act`, scrape `actions`) and by render scripts and element screenshots. act_step_failed `422` · Browser action failed · Not retryable · Members: `step` · Firecrawl: `422` `act_step_failed` "Action failed" A browser action in an `act` batch failed (for example `evaluate` threw). The `step` member is the zero-based index of the failed action; results of earlier actions are still returned. cdp_method_blocked `403` · CDP method not allowed · Not retryable Returned as a CDP error (JSON-RPC `error.data.code`) on the session's CDP socket, not as an HTTP status. The proxy blocks `Browser.*` except the version, permission, window and download methods CDP clients such as Playwright and Puppeteer send (downloads are kept in the session's own directory), `SystemInfo.*`, targets outside the session, host file access, and navigation to anything but `http:`, `https:` and `about:blank` (`file:`, `chrome:`, `chrome-extension:`, `view-source:`, `devtools:`, `data:`, ...). extraction_failed `502` · Extraction failed · Retryable · Firecrawl: `502` `extraction_failed` "Extraction failed" The model could not produce JSON that matches your schema after retries. Simplify the schema or the prompt. scrape_no_cached_data `404` · No cached copy · Not retryable · Firecrawl: `404` `SCRAPE_NO_CACHED_DATA` "No cached data" The scrape asked to be answered from the page cache only (Firecrawl `minAge`), and this node holds no cached copy of the URL that satisfies it. Scrape without the cache-only option to fetch the page. ## Render screenshot_not_found `404` · Screenshot not found · Not retryable No screenshot with this `shot_` ID exists in your project, or it expired. video_not_found `404` · Video not found · Not retryable No video with this `vid_` ID exists in your project, or it expired. artifact_not_found `404` · Artifact not found · Not retryable No artifact with this `art_` ID exists in your project. artifact_expired `410` · Artifact expired · Not retryable The artifact was deleted at the end of its retention period (7 days by default). Render it again. capture_failed `502` · Capture failed · Retryable · Members: `reason` The page could not be loaded or captured (navigation error, crash, or a page that never became ready). `reason` carries the browser's error. script_invalid `422` · Invalid video script · Not retryable · Members: `errors` The video script failed validation before recording started. `errors[]` points at the failing beats and steps. script_step_failed `422` · Script step failed · Not retryable · Members: `step` A step in the video script failed during recording (for example its target never appeared). Used as the video job's `error`; `step` is the path of the failed step, such as `beats/2/do/0`. restyle_unavailable `409` · Restyle not available · Not retryable The source video has no archived raw capture: it did not succeed, or its raw capture expired. Record the video again. style_invalid `422` · Invalid style · Not retryable · Members: `errors` A style value is unknown or malformed (preset, frame, font, color or gradient). `errors[]` points at it. ## Sandboxes sandbox_not_found `404` · Sandbox not found · Not retryable No sandbox with this `sbx_` ID exists in your project. sandbox_not_running `409` · Sandbox not running · Not retryable · Members: `current_status` The operation needs a running sandbox, but it is paused or stopped. `current_status` shows which. Resume a paused sandbox with `POST /v1/sandboxes/{sandbox_id}/resume`; a stopped sandbox cannot be restarted. template_not_found `404` · Template not found · Not retryable No template with this name or `tpl_` ID exists. `GET /v1/sandboxes/templates` lists them. snapshot_not_found `404` · Snapshot not found · Not retryable No snapshot with this `snap_` ID exists in your project. file_not_found `404` · File not found · Not retryable Nothing exists at this path inside the sandbox. path_invalid `422` · Invalid path · Not retryable The path must be absolute, at most 4,096 bytes, and contain no NUL bytes. not_a_directory `422` · Not a directory · Not retryable A component of the path is a file, so the operation cannot treat it as a directory. file_too_large `413` · File too large · Not retryable The file exceeds the 64 MiB per-request transfer limit. Split it, or fetch it from inside the sandbox. port_not_exposed `404` · Port not exposed · Not retryable The port is not in the sandbox's `ports` list. Ports are declared when the sandbox is created. process_not_found `404` · Process not found · Not retryable No background process with this ID is running in the sandbox. kernel_unavailable `409` · Code kernel unavailable · Not retryable `run_code` needs a sandbox created from the `code-interpreter` template. language_unsupported `422` · Language not supported · Not retryable The template's kernel does not run this language. `code-interpreter` runs `python` and `javascript`. guest_unreachable `502` · Sandbox agent unreachable · Retryable The agent inside the microVM did not answer (the guest is hung or out of memory). Retry once; if it repeats, delete the sandbox and create a new one. snapshot_failed `500` · Snapshot failed · Retryable Writing the snapshot failed. The sandbox keeps running unchanged; retry the snapshot. fork_unavailable `409` · Fork not available · Not retryable Forking needs a sandbox created with `forkable: true`, which enables dirty-page tracking. ## Routines routine_not_found `404` · Routine not found · Not retryable No routine with this ID or name exists in your project. routine_version_not_found `404` · Routine version not found · Not retryable The routine has no version with this `ver_` ID or number. run_not_found `404` · Run not found · Not retryable No routine run with this `run_` ID exists in your project. Run history is kept for 30 days. hook_not_found `404` · Hook not found · Not retryable No webhook trigger with this `hk_` ID exists, or its routine was deleted. routine_invalid `422` · Invalid routine · Not retryable · Members: `errors` The routine definition failed schema validation or compilation (unknown step reference, dependency cycle, CEL parse error or unknown name). `errors[]` points into the request body, for example `/steps/2/with/url`. routine_name_taken `409` · Routine name taken · Not retryable Another routine in this project already has this name. `POST /v1/routines` only creates; use `PUT /v1/routines/{name}` to publish a new version of an existing routine. run_not_waiting `409` · Run is not waiting for this signal · Not retryable The run can no longer receive this signal: it already finished, or 16 signals of this name are already buffered. Signals sent before their `wait` step starts are buffered (up to 16 per name) and consumed in order. run_as_revoked `403` · Publishing key revoked · Not retryable Routine runs execute as the key that published the active version, and that key is revoked or expired. Its triggers are paused. Publish a new version with a valid key to resume. webhook_signature_invalid `401` · Webhook verification failed · Not retryable · Members: `reason` The inbound webhook failed verification. The `reason` member is `signature` (missing or not matching) or `timestamp` (the signed timestamp is missing or further from the node's clock than the tolerance: a routine trigger's `tolerance_s` or a pack trigger's `verify.toleranceS`, at most 300 seconds for both). For a delivery the edge queued while the node was down and replays later, the tolerance applies to the time the edge received it, which the edge signs; a bad edge signature is `signature` too. step_failed `422` · Step failed · Not retryable · Members: `step` Used as a run's `error` when a step failed after its retries and had no `continue_on_error`. `step` is the step ID; the step's own error is in the run's `steps[]`. expression_error `422` · Expression error · Not retryable · Members: `step` A `${{ }}` expression failed at run time (for example a missing field or a type mismatch). Used in step errors; `step` is the step ID. run_input_invalid `422` · Invalid run input · Not retryable · Members: `errors` The run's `input` (after the routine's `inputs` defaults were applied) does not match the routine's `inputs` schema. `errors[]` points into the request body, for example `/input/topic`. step_timed_out `504` · Step timed out · Retryable Used as a step's `error` when an attempt ran past its `timeout_ms` (or `defaults.timeout_ms`). Pure and read steps retry it under their retry policy; write steps retry only when their own `retry` asks for it. step_outcome_unknown `409` · Step outcome unknown · Not retryable Used as a step's `error` after a restart of a `strict` run: the node had recorded the intent to run this `irreversible` step but not its result, so it cannot know whether the effect happened and does not repeat it. Check the destination, then start a new run if needed. hook_attestation_unverifiable `503` · Webhook replay cannot be checked yet · Retryable · Members: `retry_after_s` The edge replayed a webhook delivery it queued while the node was down, the provider's signed timestamp is outside the tolerance of the node's clock, and the edge signed its receive time with a key id (`x-b3os-edge-kid`) this node does not trust yet. The edge keeps the delivery and retries it. Operators add the edge key to `[[auth.edge_keys]]`. ## Actions and triggers pack_not_found `404` · Pack not found · Not retryable No pack with this ID (`/`, for example `io.b3os/github`) is available. pack_version_not_found `404` · Pack version not found · Not retryable The pack has no version that satisfies this version or range. action_not_found `404` · Action not found · Not retryable The pack version has no action with this key. `GET /v1/actions/search` finds actions by name and description. trigger_not_found `404` · Trigger not found · Not retryable The pack version has no trigger with this key. trigger_subscription_not_found `404` · Trigger subscription not found · Not retryable No trigger subscription with this `tsub_` ID exists in your project. Subscriptions exist while a published routine version has the `type: action` trigger that created them; a rollback, a version without that trigger, or deleting the routine removes them. action_ref_invalid `400` · Invalid action reference · Not retryable The reference does not match `//@`, for example `io.b3os/github/create-issue@1.0.0`. The namespace is reverse-DNS with at least one dot. action_input_invalid `422` · Invalid action input · Not retryable · Members: `errors` The input does not match the action's input schema. `errors[]` points into the request body, for example `/input/title`. action_output_invalid `502` · Upstream returned unexpected data · Not retryable · Members: `upstream_status` The upstream answered, but the mapped result does not match the action's output schema. Report it to the pack publisher. action_memory_exceeded `502` · Action ran out of memory · Not retryable A JavaScript (T1) action used more memory than its limit (`execution.memoryMb` in the pack manifest, 128 MB by default) and was stopped. The same input fails the same way: send less data per call, or report it to the pack publisher. connection_required `422` · Connection required · Not retryable The action needs a stored credential and none was supplied, or the caller may not use the one supplied (it needs `vault:run`, and sandbox principals need the connection in `api.connections`). connection_mismatch `422` · Connection does not match · Not retryable The connection's kind, pack or bound hosts do not match what the action declares. pack_unavailable `503` · Pack unavailable · Retryable The node could not load this pack version: it failed content-hash or publisher-signature verification, or the download from the registry failed. action_expression_error `422` · Action expression failed · Not retryable · Members: `errors` A `${{ }}` expression in the pack failed for this input before anything was sent (a missing field, a type mismatch, a URL that does not parse, a header with CR or LF), or a webhook delivery could not be evaluated by the trigger's dedupe key, filter or handshake. `errors[]` names the template field. Nothing reached the upstream; if the input is valid, report it to the pack publisher. ## Vault connection_not_found `404` · Connection not found · Not retryable No connection with this `conn_` ID exists in your project. connection_invalid `422` · Invalid connection · Not retryable · Members: `errors` The secret fields do not match the connection kind (for example `basic` without `password`), or a bound host is not a valid hostname. `errors[]` points at the field; secret values are never echoed. blob_not_found `404` · Stored object not found · Not retryable An encrypted object the vault keeps for another product (such as a browser profile's storage state) does not exist. Products usually report their own not-found code instead. blob_too_large `413` · Stored object too large · Not retryable An object another product asked the vault to store (such as a browser profile's storage state) is larger than the vault keeps per object (16 MiB by default). Store less state, for example by clearing large localStorage or IndexedDB entries before saving the profile. vault_unavailable `503` · Vault unavailable · Retryable · Members: `retry_after_s` The vault on this node is not unlocked yet (its key is not loaded). Retry shortly; operations that need credentials fail until then. ## Infer `/v1/infer/*` operations use the OpenAI error shape `{"error": {"message", "type", "code", "param"}}` with the B3OS code in `error.code`. `GET /v1/infer/audio/voices` is a B3OS endpoint and returns problems. model_not_available `404` · Model not available · Not retryable The model is not served on this node. `GET /v1/infer/models` lists the models that are. To use a model from the B3IQ gateway instead, set `"route": "gateway"`; B3OS never falls back silently. context_length_exceeded `400` · Context length exceeded · Not retryable The prompt plus `max_tokens` exceeds the model's context window (`b3os.context_length` in the model list). unsupported_parameter `400` · Unsupported parameter · Not retryable The model or runtime does not support a parameter you sent (for example `n` greater than 1, image input on a text-only model, or an audio format that is not enabled). The message names the parameter. voice_not_found `404` · Voice not found · Not retryable The voice is not available for this speech model. `GET /v1/infer/audio/voices` lists them. infer_backend_unavailable `503` · Model runtime unavailable · Retryable · Members: `retry_after_s` · Firecrawl: `503` `infer_backend_unavailable` "Service Unavailable" The model runtime on the node is restarting or overloaded. Retry after `Retry-After` seconds. ## Firecrawl compatibility These codes appear only on `/compat/firecrawl/*`. Every other code that path can return has its Firecrawl mapping listed in its own entry. unsupported_endpoint `404` · Endpoint not supported · Not retryable · Firecrawl: `404` `unsupported_endpoint` "Endpoint not supported by B3OS" The Firecrawl endpoint exists upstream but B3OS does not implement it. The problem's `detail` is the B3OS alternative (the operation's `x-b3os-unsupported.alternative`), for example the native `/v1/vision/sessions` API instead of `/v2/interact`, so the Firecrawl `error` reads `Endpoint not supported by B3OS: `. unsupported_option `400` · Option not supported · Not retryable · Firecrawl: `400` `unsupported_option` "Option not supported by B3OS" The request uses a Firecrawl option B3OS cannot honor (for example `proxy: "enhanced"` or the `branding` format). The problem's `detail` names the option, so the Firecrawl `error` reads `Option not supported by B3OS: `. B3OS refuses rather than silently ignoring it.