Errors

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#<code>). instance is the request ID, the same value as the x-request-id header; GET /v1/requests/{request_id} 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/<name>, #path/<name>, #header/<name>) 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 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/<name>, #path/<name> or #header/<name> 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 <key> 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/<sandbox>/<port>/<token>/). 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 <capability token>, 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": "<code>", "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 (<namespace>/<name>, 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 <namespace>/<name>/<action>@<version>, 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: <alternative>.

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: <detail>. B3OS refuses rather than silently ignoring it.