> ## 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. # List deploys Deploys of your organization's applications, newest first, without their plans and items (get one deploy for those). Deploys are kept 90 days; the live one is always kept. ` GET /v1/deploys ` List deploys Deploys of your organization's applications, newest first, without their plans and items (get one deploy for those). Deploys are kept 90 days; the live one is always kept. ## Servers - ` https://beta-api.b3os.org ` — API (API keys and CLI tokens) - ` https://beta.b3os.org ` — Dashboard (session cookie and CSRF header; same paths) ## Authentication The operation accepts these alternatives. Schemes within one alternative are required together. ### Alternative 1 - ` apiKey `: ` http ` - HTTP scheme: ` bearer ` (b3os_sk_ API key or b3os_pat_ token) - `Authorization: Bearer `. Two credential kinds are accepted: - **API keys** `b3os_sk_<32 base32>_`, created in the dashboard or with `POST /v1/keys`. A key belongs to one project, has scopes, an optional spend cap and expiry, and is shown only once. - **CLI tokens** `b3os_pat_<32 base32>_`, issued by the device login (`b3os login`). They act for one user in the organization and project chosen at approval. Keys are stored as SHA-256 hashes. The edge exchanges them for a 60-second node token before forwarding a request to a node, so nodes never see your key. ## Parameters ### ` app ` (query, optional) Only this application's deploys. - ` value `: type ` string ` — An application's name, the `name` in its b3os.yaml. - minLength: ` 1 ` - maxLength: ` 63 ` - pattern: ` "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$" ` ### ` env ` (query, optional) Only this environment's deploys (`production`). - ` value `: type ` string ` - maxLength: ` 63 ` ### ` project_id ` (query, optional) Only deploys into this project. Environments are projects in this beta, so one application name in a staging and a production project has two lists. - ` value `: type ` string ` - pattern: ` "^prj_[0-9a-hjkmnp-tv-z]{26}$" ` ### ` status ` (query, optional) Only deploys in this status. - ` value `: type ` string ` — `queued` (waiting its turn), `building` (plan, routines, builds and new service generations, all undone on a failure), `applying` (the cutover), `live` (what the application runs now, also when something went wrong after its cutover: `error` says what), `superseded` (was live; a newer deploy went live), `failed`, `cancelled` (stopped before it started: a newer commit, an unlinked repository, a removed installation; or stopped part-way and undone: a cancelled workflow run, Ctrl-C, a newer deploy) or `skipped` (nothing the manifest reads changed, auto-deploy is paused, or the branch had already moved past the pushed commit). - enum: ` ["queued","building","applying","live","superseded","failed","cancelled","skipped"] ` ### ` limit ` (query, optional) Page size, from 1 to 100. - ` value `: type ` integer ` - default: ` 20 ` - minimum: ` 1 ` - maximum: ` 100 ` ### ` cursor ` (query, optional) Opaque cursor from the previous page's `next_cursor`. Omit it for the first page. - ` value `: type ` string ` - maxLength: ` 512 ` ## Responses ### ` 200 ` — A page of deploys. Content type: ` application/json ` - ` value `: type ` unknown ` - ` allOf constraint 1 `: type ` object ` — A page of results. Pass `next_cursor` as `cursor` to get the next page; it is `null` on the last page. Pages are ordered newest first unless the operation says otherwise. - Required fields: ` object `, ` data `, ` next_cursor ` - ` object `: type ` string ` - enum: ` ["list"] ` - ` data `: type ` array ` - ` array item `: type ` unknown ` - ` next_cursor `: type ` string `; nullable - ` allOf constraint 2 `: type ` object ` - ` data `: type ` array ` - ` array item `: type ` object ` — A deploy of one application environment from one commit. - Required fields: ` id `, ` object `, ` app `, ` env `, ` project_id `, ` status `, ` source `, ` requested_by `, ` commit `, ` repository `, ` installation_id `, ` manifest_path `, ` manifest_sha `, ` previous_id `, ` rollback_of `, ` plan_summary `, ` checks `, ` error `, ` reason `, ` github_error `, ` attempts `, ` created_at `, ` updated_at `, ` started_at `, ` live_at `, ` finished_at ` - ` id `: type ` string ` - pattern: ` "^dep_[0-9a-hjkmnp-tv-z]{26}$" ` - ` object `: type ` string ` - enum: ` ["deploy"] ` - ` app `: type ` string ` — An application's name, the `name` in its b3os.yaml. - minLength: ` 1 ` - maxLength: ` 63 ` - pattern: ` "^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$" ` - ` env `: type ` string ` - ` project_id `: type ` string ` - ` status `: type ` string ` — `queued` (waiting its turn), `building` (plan, routines, builds and new service generations, all undone on a failure), `applying` (the cutover), `live` (what the application runs now, also when something went wrong after its cutover: `error` says what), `superseded` (was live; a newer deploy went live), `failed`, `cancelled` (stopped before it started: a newer commit, an unlinked repository, a removed installation; or stopped part-way and undone: a cancelled workflow run, Ctrl-C, a newer deploy) or `skipped` (nothing the manifest reads changed, auto-deploy is paused, or the branch had already moved past the pushed commit). - enum: ` ["queued","building","applying","live","superseded","failed","cancelled","skipped"] ` - ` source `: type ` string ` — What ran the deploy: `github_app` (a push to the linked branch, or Deploy in the dashboard), `redeploy` and `rollback` (the dashboard's, through the GitHub App), or `b3os apply`, which records its own deploys: `cli` from a machine, `github_actions` from a workflow. - enum: ` ["cli","github_actions","github_app","redeploy","rollback"] ` - ` requested_by `: type ` string `; nullable — The GitHub login that pushed (or that ran the workflow, for `github_actions`), or the user or key that asked for a redeploy or rollback, or that ran `b3os apply` (`cli`). - ` commit `: type ` object `; nullable - Required fields: ` sha `, ` message `, ` branch `, ` dirty ` - ` sha `: type ` string ` - ` message `: type ` string `; nullable - ` branch `: type ` string `; nullable - ` dirty `: type ` boolean ` — The tree held uncommitted changes, which deployed with it (`b3os apply` from a machine). - ` repository `: type ` object `; nullable - Required fields: ` id `, ` full_name ` - ` id `: type ` integer `; nullable — GitHub's id; null when `b3os apply` named the repository without it. - ` full_name `: type ` string ` - ` installation_id `: type ` integer `; nullable - ` manifest_path `: type ` string ` - ` manifest_sha `: type ` string `; nullable - ` previous_id `: type ` string `; nullable — The deploy that was live before this one went live. - ` rollback_of `: type ` string `; nullable — The deploy a rollback ran again: the dashboard's (`source: rollback`), or `b3os app rollback`'s (`source: cli` or `github_actions`). - ` recreated `: type ` array `; nullable — A deploy `b3os apply --keepalive` recorded because it recreated services: each one and why, with its lost process's last lines. Null for any other deploy, and absent from edges before 2026-11-11. - ` array item `: type ` object ` — A service `b3os apply --keepalive` started again, and why: its process exited (`process`), its microVM failed (`crash`), its lease ended with no renewal (`lease`), it failed its readiness probe (`probe`), or it stopped for another reason (`stopped`). `lines` are the last lines the lost process printed (at most 20, each cut to 300 characters, credentials in URLs and paths redacted), which its deleted sandbox no longer serves. - Required fields: ` item `, ` cause `, ` reason `, ` lines ` - ` item `: type ` string ` — `service/`. - pattern: ` "^service/[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$" ` - ` cause `: type ` string ` - enum: ` ["process","crash","lease","probe","stopped"] ` - ` reason `: type ` string ` — In words, with the time in UTC (`process 466 killed by TERM at 01:15:37 UTC`, `the lease ended at 20:24:07 UTC`). - maxLength: ` 300 ` - ` lines `: type ` array ` - maxItems: ` 20 ` - ` array item `: type ` string ` - maxLength: ` 300 ` - ` plan_summary `: type ` object `; nullable — Plan items per action. - ` create `: type ` integer ` - ` update `: type ` integer ` - ` ok `: type ` integer ` - ` gap `: type ` integer ` - ` problem `: type ` integer ` - ` unchecked `: type ` integer ` - ` remove `: type ` integer ` - ` plan `: type ` object `; nullable — Get a deploy only. The plan as `b3os apply --dry-run` printed it, with its findings. - ` text `: type ` string ` - ` summary `: type ` object ` — Plan items per action. - ` create `: type ` integer ` - ` update `: type ` integer ` - ` ok `: type ` integer ` - ` gap `: type ` integer ` - ` problem `: type ` integer ` - ` unchecked `: type ` integer ` - ` remove `: type ` integer ` - ` findings `: type ` array ` - ` array item `: type ` object ` - ` items `: type ` array ` — Get a deploy only. Per item, what the deploy did and the ids it made, and since 2026-11-11 when each step began and ended (`started_at`, `ended_at`; a new generation also `probe` and `cutover`, each with both times). Older records have no times. - ` array item `: type ` object ` - ` output `: type ` array ` — Get a deploy only. What the processes of a deploy B3OS ran printed, per step (a build's apt step when `build.apt` lists packages, a build's install, a generation's prepare), in the order the steps started: the last 400 lines or 64 KiB of each, whichever is smaller, with credentials in URLs and paths redacted. Written as the output arrives, about every 5 seconds while a step runs, so a deploy that is building shows its install as it goes. Empty for a deploy `b3os apply` recorded: it prints the output where it runs. - ` array item `: type ` object ` — The output of one step of a deploy, as the deployer kept it. - Required fields: ` item `, ` step `, ` status `, ` lines `, ` dropped `, ` started_at `, ` ended_at ` - ` item `: type ` string ` — The item the step belongs to (`build/agent` for an apt step or an install, `service/agent` for a prepare). - ` step `: type ` string ` — `apt` is the build's `apt-get install` of `build.apt`, run as root before `install`. - enum: ` ["install","prepare","apt"] ` - ` status `: type ` string ` — `running` while the process runs; a step the deploy stopped before it ended is `failed`. - enum: ` ["running","succeeded","failed"] ` - ` lines `: type ` array ` — The newest lines, oldest first, without their newline. - maxItems: ` 400 ` - ` array item `: type ` string ` - maxLength: ` 2000 ` - ` dropped `: type ` integer ` — Earlier lines that are no longer kept. - minimum: ` 0 ` - ` started_at `: type ` string `; format ` date-time ` - ` ended_at `: type ` string `; nullable; format ` date-time ` - ` step `: type ` string `; nullable — Where the deploy is, in the deployer's words (`build/agent install-wait (2 min)`, `service/agent ready`), as it last reported; null before it starts. - ` run_url `: type ` string `; nullable — The GitHub Actions run that deployed it (`source: github_actions`). - ` checks `: type ` object ` — The check runs on the commit (GitHub ids). - Required fields: ` deploy `, ` plan ` - ` deploy `: type ` integer `; nullable - ` plan `: type ` integer `; nullable - ` error `: type ` string `; nullable — Why it failed. On a `live` deploy: what went wrong after its cutover (a retire, a service that stopped, a run cut short); its new generations serve anyway, and B3OS keeps them alive. - ` reason `: type ` string `; nullable — Why it was cancelled or skipped. On a `live` deploy `b3os apply` recorded: that it replaced a deploy B3OS kept alive, so nothing but `b3os apply` renews the application now. - ` github_error `: type ` string `; nullable — The last check run or comment GitHub refused (the deploy went on without it). - ` attempts `: type ` integer ` - ` created_at `: type ` string `; format ` date-time ` - ` updated_at `: type ` string `; format ` date-time ` - ` started_at `: type ` string `; nullable; format ` date-time ` - ` live_at `: type ` string `; nullable; format ` date-time ` - ` finished_at `: type ` string `; nullable; format ` date-time ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`, then `edge_colo`, which has no duration and names the Cloudflare location and ray ID. The `desc` of `edge_auth` names the steps it waited on as `=:`: `key` (`isolate`, `colo` or `primary`), `limits` (`key` when they came with the key's read, `cache` or `d1`) and `permit` (`lease` or `limiter`, or `optimistic` when the call went ahead and was counted right after). They are time inside `edge_auth`, not added to it. - ` value `: type ` string ` Example: ```json { "object": "list", "data": [ { "id": "dep_01m6a2zq8x9hkqd3n7c5b4v2tw", "object": "deploy", "app": "research-agent", "env": "production", "project_id": "prj_01m5t3pf8heewxt65ej3dm577y", "status": "live", "source": "github_app", "requested_by": "dana", "commit": { "sha": "3f2c1b0a9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a", "message": "Update the harness", "branch": "main", "dirty": false }, "repository": { "id": 812345678, "full_name": "acme/research-agent" }, "installation_id": 61234567, "manifest_path": "b3os.yaml", "manifest_sha": "0123456789ab", "previous_id": null, "rollback_of": null, "plan_summary": { "create": 1, "update": 0, "ok": 1, "gap": 0, "problem": 0, "unchecked": 0, "remove": 0 }, "step": null, "run_url": null, "checks": { "deploy": 2100000001, "plan": 2100000002 }, "error": null, "reason": null, "github_error": null, "attempts": 0, "created_at": "2026-11-07T09:10:00.000Z", "updated_at": "2026-11-07T09:12:00.000Z", "started_at": "2026-11-07T09:10:05.000Z", "live_at": "2026-11-07T09:12:00.000Z", "finished_at": "2026-11-07T09:12:00.000Z" } ], "next_cursor": null } ``` ### ` 400 ` — The request failed validation (`invalid_request`, `invalid_url`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` - ` option `: type ` string ` — The option a request value was refused for, by its id (`option_not_allowed`), e.g. `sandboxes.clone_reset`. - ` value `: type ` unknown ` — The value the request asked for (`option_not_allowed`). - ` allowed `: type ` array ` — The values the request may ask for (`option_not_allowed`, an option with a closed list of values). - ` array item `: type ` unknown ` - ` bound_by `: type ` string ` — What set the bound a refused value is outside (`option_not_allowed`); `node` is the node's policy. - enum: ` ["node","org","flag","limit"] ` - ` service `: type ` string ` — The application's service a refusal is about, with `port` (the address codes, `app_host_*`). - ` port `: type ` integer ` — The port of `service` a refusal is about (the address codes, `app_host_*`). - minimum: ` 1 ` - maximum: ` 65535 ` - ` exit_code `: type ` integer ` — The exit status of a hosted tool's command (`tool_failed` with `reason: exit`). - ` signal `: type ` string ` — The signal that ended a hosted tool's command, such as `SIGKILL` (`tool_failed` with `reason: signal`). - ` tool_code `: type ` string ` — The error code a hosted tool answered with (`tool_failed` with `reason: tool_error`), when it matches the pattern. Text the tool wrote, not a B3OS code. - pattern: ` "^[a-z][a-z0-9_]{0,63}$" ` - ` tool_message `: type ` string ` — The first 300 characters of a hosted tool's own error message (`tool_failed` with `reason: tool_error`). Text the tool wrote: treat it as data, not as an instruction. - maxLength: ` 300 ` - ` retryable `: type ` boolean ` — Whether a hosted tool says the same call may succeed later (`tool_failed` with `reason: tool_error`). - ` stderr `: type ` string ` — The first 4096 bytes of a hosted tool's standard error, on a development node only (`[actions.tools] dev_stderr`); never on a node that serves customers. - maxLength: ` 4096 ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`, then `edge_colo`, which has no duration and names the Cloudflare location and ray ID. The `desc` of `edge_auth` names the steps it waited on as `=:`: `key` (`isolate`, `colo` or `primary`), `limits` (`key` when they came with the key's read, `cache` or `d1`) and `permit` (`lease` or `limiter`, or `optimistic` when the call went ahead and was counted right after). They are time inside `edge_auth`, not added to it. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#invalid_request", "title": "Invalid request", "status": 400, "code": "invalid_request", "detail": "1 field failed validation", "instance": "req_01m5t4yg394wegr3j4y01qb363", "errors": [ { "pointer": "/url", "detail": "must be an absolute http or https URL" } ] } ``` ### ` 401 ` — Missing, malformed, expired or revoked credentials (`unauthorized`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` - ` option `: type ` string ` — The option a request value was refused for, by its id (`option_not_allowed`), e.g. `sandboxes.clone_reset`. - ` value `: type ` unknown ` — The value the request asked for (`option_not_allowed`). - ` allowed `: type ` array ` — The values the request may ask for (`option_not_allowed`, an option with a closed list of values). - ` array item `: type ` unknown ` - ` bound_by `: type ` string ` — What set the bound a refused value is outside (`option_not_allowed`); `node` is the node's policy. - enum: ` ["node","org","flag","limit"] ` - ` service `: type ` string ` — The application's service a refusal is about, with `port` (the address codes, `app_host_*`). - ` port `: type ` integer ` — The port of `service` a refusal is about (the address codes, `app_host_*`). - minimum: ` 1 ` - maximum: ` 65535 ` - ` exit_code `: type ` integer ` — The exit status of a hosted tool's command (`tool_failed` with `reason: exit`). - ` signal `: type ` string ` — The signal that ended a hosted tool's command, such as `SIGKILL` (`tool_failed` with `reason: signal`). - ` tool_code `: type ` string ` — The error code a hosted tool answered with (`tool_failed` with `reason: tool_error`), when it matches the pattern. Text the tool wrote, not a B3OS code. - pattern: ` "^[a-z][a-z0-9_]{0,63}$" ` - ` tool_message `: type ` string ` — The first 300 characters of a hosted tool's own error message (`tool_failed` with `reason: tool_error`). Text the tool wrote: treat it as data, not as an instruction. - maxLength: ` 300 ` - ` retryable `: type ` boolean ` — Whether a hosted tool says the same call may succeed later (`tool_failed` with `reason: tool_error`). - ` stderr `: type ` string ` — The first 4096 bytes of a hosted tool's standard error, on a development node only (`[actions.tools] dev_stderr`); never on a node that serves customers. - maxLength: ` 4096 ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`, then `edge_colo`, which has no duration and names the Cloudflare location and ray ID. The `desc` of `edge_auth` names the steps it waited on as `=:`: `key` (`isolate`, `colo` or `primary`), `limits` (`key` when they came with the key's read, `cache` or `d1`) and `permit` (`lease` or `limiter`, or `optimistic` when the call went ahead and was counted right after). They are time inside `edge_auth`, not added to it. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#unauthorized", "title": "Unauthorized", "status": 401, "code": "unauthorized", "detail": "API key checksum does not match; check that the whole key was copied", "instance": "req_01m5t4yg394wegr3j4y01qb363", "reason": "malformed" } ``` ### ` 403 ` — Authenticated but not allowed (`forbidden`, `egress_denied`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` - ` option `: type ` string ` — The option a request value was refused for, by its id (`option_not_allowed`), e.g. `sandboxes.clone_reset`. - ` value `: type ` unknown ` — The value the request asked for (`option_not_allowed`). - ` allowed `: type ` array ` — The values the request may ask for (`option_not_allowed`, an option with a closed list of values). - ` array item `: type ` unknown ` - ` bound_by `: type ` string ` — What set the bound a refused value is outside (`option_not_allowed`); `node` is the node's policy. - enum: ` ["node","org","flag","limit"] ` - ` service `: type ` string ` — The application's service a refusal is about, with `port` (the address codes, `app_host_*`). - ` port `: type ` integer ` — The port of `service` a refusal is about (the address codes, `app_host_*`). - minimum: ` 1 ` - maximum: ` 65535 ` - ` exit_code `: type ` integer ` — The exit status of a hosted tool's command (`tool_failed` with `reason: exit`). - ` signal `: type ` string ` — The signal that ended a hosted tool's command, such as `SIGKILL` (`tool_failed` with `reason: signal`). - ` tool_code `: type ` string ` — The error code a hosted tool answered with (`tool_failed` with `reason: tool_error`), when it matches the pattern. Text the tool wrote, not a B3OS code. - pattern: ` "^[a-z][a-z0-9_]{0,63}$" ` - ` tool_message `: type ` string ` — The first 300 characters of a hosted tool's own error message (`tool_failed` with `reason: tool_error`). Text the tool wrote: treat it as data, not as an instruction. - maxLength: ` 300 ` - ` retryable `: type ` boolean ` — Whether a hosted tool says the same call may succeed later (`tool_failed` with `reason: tool_error`). - ` stderr `: type ` string ` — The first 4096 bytes of a hosted tool's standard error, on a development node only (`[actions.tools] dev_stderr`); never on a node that serves customers. - maxLength: ` 4096 ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`, then `edge_colo`, which has no duration and names the Cloudflare location and ray ID. The `desc` of `edge_auth` names the steps it waited on as `=:`: `key` (`isolate`, `colo` or `primary`), `limits` (`key` when they came with the key's read, `cache` or `d1`) and `permit` (`lease` or `limiter`, or `optimistic` when the call went ahead and was counted right after). They are time inside `edge_auth`, not added to it. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#forbidden", "title": "Forbidden", "status": 403, "code": "forbidden", "detail": "This key lacks the scope sandboxes:write", "instance": "req_01m5t4yg394wegr3j4y01qb363", "reason": "scope", "required_scope": "sandboxes:write" } ``` ### ` 429 ` — A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` - ` option `: type ` string ` — The option a request value was refused for, by its id (`option_not_allowed`), e.g. `sandboxes.clone_reset`. - ` value `: type ` unknown ` — The value the request asked for (`option_not_allowed`). - ` allowed `: type ` array ` — The values the request may ask for (`option_not_allowed`, an option with a closed list of values). - ` array item `: type ` unknown ` - ` bound_by `: type ` string ` — What set the bound a refused value is outside (`option_not_allowed`); `node` is the node's policy. - enum: ` ["node","org","flag","limit"] ` - ` service `: type ` string ` — The application's service a refusal is about, with `port` (the address codes, `app_host_*`). - ` port `: type ` integer ` — The port of `service` a refusal is about (the address codes, `app_host_*`). - minimum: ` 1 ` - maximum: ` 65535 ` - ` exit_code `: type ` integer ` — The exit status of a hosted tool's command (`tool_failed` with `reason: exit`). - ` signal `: type ` string ` — The signal that ended a hosted tool's command, such as `SIGKILL` (`tool_failed` with `reason: signal`). - ` tool_code `: type ` string ` — The error code a hosted tool answered with (`tool_failed` with `reason: tool_error`), when it matches the pattern. Text the tool wrote, not a B3OS code. - pattern: ` "^[a-z][a-z0-9_]{0,63}$" ` - ` tool_message `: type ` string ` — The first 300 characters of a hosted tool's own error message (`tool_failed` with `reason: tool_error`). Text the tool wrote: treat it as data, not as an instruction. - maxLength: ` 300 ` - ` retryable `: type ` boolean ` — Whether a hosted tool says the same call may succeed later (`tool_failed` with `reason: tool_error`). - ` stderr `: type ` string ` — The first 4096 bytes of a hosted tool's standard error, on a development node only (`[actions.tools] dev_stderr`); never on a node that serves customers. - maxLength: ` 4096 ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`, then `edge_colo`, which has no duration and names the Cloudflare location and ray ID. The `desc` of `edge_auth` names the steps it waited on as `=:`: `key` (`isolate`, `colo` or `primary`), `limits` (`key` when they came with the key's read, `cache` or `d1`) and `permit` (`lease` or `limiter`, or `optimistic` when the call went ahead and was counted right after). They are time inside `edge_auth`, not added to it. - ` value `: type ` string ` Response header ` Retry-After ` — Seconds to wait before retrying or polling again. - ` value `: type ` integer ` - minimum: ` 0 ` Response header ` RateLimit-Limit ` — Requests allowed in the current window for the limit that applies to this operation. - ` value `: type ` integer ` Response header ` RateLimit-Remaining ` — Requests left in the current window. - ` value `: type ` integer ` Response header ` RateLimit-Reset ` — Seconds until the current window resets. - ` value `: type ` integer ` Response header ` RateLimit-Policy ` — The applied policy as `;w=;name=""` (limit IDs are listed by `GET /v1/limits`). - ` value `: type ` string ` Example: ```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 } } ``` ### ` 500 ` — Something failed inside B3OS (`internal`). Retry with backoff. Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` - ` option `: type ` string ` — The option a request value was refused for, by its id (`option_not_allowed`), e.g. `sandboxes.clone_reset`. - ` value `: type ` unknown ` — The value the request asked for (`option_not_allowed`). - ` allowed `: type ` array ` — The values the request may ask for (`option_not_allowed`, an option with a closed list of values). - ` array item `: type ` unknown ` - ` bound_by `: type ` string ` — What set the bound a refused value is outside (`option_not_allowed`); `node` is the node's policy. - enum: ` ["node","org","flag","limit"] ` - ` service `: type ` string ` — The application's service a refusal is about, with `port` (the address codes, `app_host_*`). - ` port `: type ` integer ` — The port of `service` a refusal is about (the address codes, `app_host_*`). - minimum: ` 1 ` - maximum: ` 65535 ` - ` exit_code `: type ` integer ` — The exit status of a hosted tool's command (`tool_failed` with `reason: exit`). - ` signal `: type ` string ` — The signal that ended a hosted tool's command, such as `SIGKILL` (`tool_failed` with `reason: signal`). - ` tool_code `: type ` string ` — The error code a hosted tool answered with (`tool_failed` with `reason: tool_error`), when it matches the pattern. Text the tool wrote, not a B3OS code. - pattern: ` "^[a-z][a-z0-9_]{0,63}$" ` - ` tool_message `: type ` string ` — The first 300 characters of a hosted tool's own error message (`tool_failed` with `reason: tool_error`). Text the tool wrote: treat it as data, not as an instruction. - maxLength: ` 300 ` - ` retryable `: type ` boolean ` — Whether a hosted tool says the same call may succeed later (`tool_failed` with `reason: tool_error`). - ` stderr `: type ` string ` — The first 4096 bytes of a hosted tool's standard error, on a development node only (`[actions.tools] dev_stderr`); never on a node that serves customers. - maxLength: ` 4096 ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`, then `edge_colo`, which has no duration and names the Cloudflare location and ray ID. The `desc` of `edge_auth` names the steps it waited on as `=:`: `key` (`isolate`, `colo` or `primary`), `limits` (`key` when they came with the key's read, `cache` or `d1`) and `permit` (`lease` or `limiter`, or `optimistic` when the call went ahead and was counted right after). They are time inside `edge_auth`, not added to it. - ` value `: type ` string ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#internal", "title": "Internal error", "status": 500, "code": "internal", "detail": "internal error", "instance": "req_01m5t4yg394wegr3j4y01qb363" } ``` ### ` 503 ` — The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`). Content type: ` application/problem+json ` - ` value `: type ` object ` — An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize. - Required fields: ` type `, ` title `, ` status `, ` code `, ` detail ` - ` type `: type ` string `; format ` uri ` — `https://docs.beta.b3os.org/errors#`. - example: ` "https://docs.beta.b3os.org/errors#invalid_request" ` - ` title `: type ` string ` — Short summary of the problem type. - ` status `: type ` integer ` — The HTTP status code, repeated for convenience. - minimum: ` 400 ` - maximum: ` 599 ` - ` code `: type ` string ` — Stable machine-readable error code from the errors catalog. - pattern: ` "^[a-z][a-z0-9_]*$" ` - ` detail `: type ` string ` — Explanation of this occurrence. Never contains secrets. - ` instance `: type ` string ` — The request ID (`req_…`) of the request that failed. Include it when you contact support. - example: ` "req_01m5t4yg394wegr3j4y01qb363" ` - ` errors `: type ` array ` — Validation problems, one per field (`invalid_request` and the other codes that list `errors`). - ` array item `: type ` object ` — One validation problem. - Required fields: ` pointer `, ` detail ` - ` pointer `: type ` string ` — Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/`, `#path/` or `#header/` for parameters. - example: ` "/url" ` - ` detail `: type ` string ` — What is wrong there. - example: ` "must be an absolute http or https URL" ` - ` reason `: type ` string ` — Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …). - ` required_scope `: type ` string ` — The scope that was missing (`forbidden` with `reason: scope`). - ` retry_after_s `: type ` integer ` — Same value as the `Retry-After` header, for clients that only read the body. - minimum: ` 0 ` - ` limit `: type ` object ` — The limit an error refers to. IDs and current values are listed by `GET /v1/limits`. - Required fields: ` id `, ` limit `, ` unit ` - ` id `: type ` string ` — Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`. - example: ` "vision.scrape.rpm" ` - ` limit `: type ` number ` — The limit's value. - ` unit `: type ` string ` — What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`. - ` window_s `: type ` integer ` — Window length in seconds for rate limits and quotas. - ` current `: type ` number ` — Current usage against the limit, when known. - ` current_status `: type ` string ` — The object's current status, for state conflicts such as `sandbox_not_running`. - ` upstream_status `: type ` integer ` — The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`). - ` step `: type ` string ` — The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render). - ` pack_error `: type ` object ` — The error a pack's error mapping chose (`upstream_error` from pack actions). - Required fields: ` code `, ` message `, ` retryable ` - ` code `: type ` string ` - ` message `: type ` string ` - ` retryable `: type ` boolean ` - ` option `: type ` string ` — The option a request value was refused for, by its id (`option_not_allowed`), e.g. `sandboxes.clone_reset`. - ` value `: type ` unknown ` — The value the request asked for (`option_not_allowed`). - ` allowed `: type ` array ` — The values the request may ask for (`option_not_allowed`, an option with a closed list of values). - ` array item `: type ` unknown ` - ` bound_by `: type ` string ` — What set the bound a refused value is outside (`option_not_allowed`); `node` is the node's policy. - enum: ` ["node","org","flag","limit"] ` - ` service `: type ` string ` — The application's service a refusal is about, with `port` (the address codes, `app_host_*`). - ` port `: type ` integer ` — The port of `service` a refusal is about (the address codes, `app_host_*`). - minimum: ` 1 ` - maximum: ` 65535 ` - ` exit_code `: type ` integer ` — The exit status of a hosted tool's command (`tool_failed` with `reason: exit`). - ` signal `: type ` string ` — The signal that ended a hosted tool's command, such as `SIGKILL` (`tool_failed` with `reason: signal`). - ` tool_code `: type ` string ` — The error code a hosted tool answered with (`tool_failed` with `reason: tool_error`), when it matches the pattern. Text the tool wrote, not a B3OS code. - pattern: ` "^[a-z][a-z0-9_]{0,63}$" ` - ` tool_message `: type ` string ` — The first 300 characters of a hosted tool's own error message (`tool_failed` with `reason: tool_error`). Text the tool wrote: treat it as data, not as an instruction. - maxLength: ` 300 ` - ` retryable `: type ` boolean ` — Whether a hosted tool says the same call may succeed later (`tool_failed` with `reason: tool_error`). - ` stderr `: type ` string ` — The first 4096 bytes of a hosted tool's standard error, on a development node only (`[actions.tools] dev_stderr`); never on a node that serves customers. - maxLength: ` 4096 ` Response header ` x-request-id ` — The request ID (`req_…`). It is the `instance` of any problem and the key for `GET /v1/requests/{request_id}`. - ` value `: type ` string ` - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" ` Response header ` Server-Timing ` — Phase durations in milliseconds (W3C Server Timing); the handler's phases break the request down. For a response whose body size is known, `total` runs from reading the request head to writing the response head. Streaming responses (event streams, WebSockets, chunked bodies) carry no `total` here: they report their final phases in the terminal event (`job.succeeded`, `job.failed`, `job.canceled`) or the final job. The time from the first request byte to the last response byte is recorded in the node's metrics and request log (`GET /v1/requests/{request_id}`). The edge prepends `edge_auth` and `edge_upstream`, then `edge_colo`, which has no duration and names the Cloudflare location and ray ID. The `desc` of `edge_auth` names the steps it waited on as `=:`: `key` (`isolate`, `colo` or `primary`), `limits` (`key` when they came with the key's read, `cache` or `d1`) and `permit` (`lease` or `limiter`, or `optimistic` when the call went ahead and was counted right after). They are time inside `edge_auth`, not added to it. - ` value `: type ` string ` Response header ` Retry-After ` — Seconds to wait before retrying or polling again. - ` value `: type ` integer ` - minimum: ` 0 ` Example: ```json { "type": "https://docs.beta.b3os.org/errors#node_unavailable", "title": "Node unavailable", "status": 503, "code": "node_unavailable", "detail": "Node n1 is not reachable; retry in 5 seconds", "instance": "req_01m5t4yg394wegr3j4y01qb363", "retry_after_s": 5 } ``` ## Request examples ### cURL ```curl curl -X GET 'https://beta-api.b3os.org/v1/deploys' \ -H 'Authorization: Bearer YOUR_API_TOKEN' ``` ### JavaScript ```javascript const response = await fetch('https://beta-api.b3os.org/v1/deploys', { method: 'GET', headers: { "Authorization": "Bearer YOUR_API_TOKEN" } }); const data = await response.json(); console.log(data); ``` ### Python ```python import requests headers = { 'Authorization': 'Bearer YOUR_API_TOKEN' } response = requests.get('https://beta-api.b3os.org/v1/deploys', headers=headers) print(response.json()) ```