> ## 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.

# Get a trace

The requests of one W3C trace in your project, in start order, with the usage each one was charged and the sandbox tags of the sandboxes that made them (`b3os.app`, `b3os.deploy`, `b3os.item`). A trace is every request whose `traceparent` named this trace id: the calls of one `traces.turn` in the SDKs, or of a harness that sends its own `traceparent`. In this beta the edge assembles it from the request log and the usage records, so `spans` are the requests themselves, listed flat (`nested: false`); calls made inside B3OS on a request's behalf (a routine step's scrape, a hosted tool) are inside their request's time and have no span of their own. `harness_ms` is the time inside the trace when no B3OS request was in flight. `origin` is `call` for one call and its retries, or for a trace made only by an SDK version that sends no trace mark (by its `User-Agent`); otherwise `traceparent`. At most 300 requests are read (`truncated`). 

` GET /v1/traces/{trace_id} `

Get a trace

The requests of one W3C trace in your project, in start order, with the usage each one was charged and the
sandbox tags of the sandboxes that made them (`b3os.app`, `b3os.deploy`, `b3os.item`). A trace is every
request whose `traceparent` named this trace id: the calls of one `traces.turn` in the SDKs, or of a harness
that sends its own `traceparent`. In this beta the edge assembles it from the request log and the usage
records, so `spans` are the requests themselves, listed flat (`nested: false`); calls made inside B3OS on
a request's behalf (a routine step's scrape, a hosted tool) are inside their request's time and have no span
of their own. `harness_ms` is the time inside the trace when no B3OS request was in flight. `origin` is
`call` for one call and its retries, or for a trace made only by an SDK version that sends no trace mark
(by its `User-Agent`); otherwise `traceparent`. At most 300 requests are read (`truncated`).


## 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 <credential>`. Two credential kinds are accepted:

- **API keys** `b3os_sk_<32 base32>_<crc32>`, 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>_<crc32>`, 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

### ` trace_id ` (path, required)

- ` value `: type ` string `

  - pattern: ` "^[0-9a-f]{32}$" `

Example:

```json
"4bf92f3577b34da6a3ce929d0e0e4736"
```

## Responses

### ` 200 ` — The trace.

Content type: ` application/json `

- ` value `: type ` object `

  - Required fields: ` id `, ` object `, ` origin `, ` nested `, ` project_id `, ` app `, ` deploy `, ` service `, ` started_at `, ` ended_at `, ` duration_ms `, ` harness_ms `, ` status `, ` counts `, ` usage `, ` sandboxes `, ` spans `, ` truncated `

  - ` id `: type ` string `

    - pattern: ` "^[0-9a-f]{32}$" `

  - ` object `: type ` string `

    - enum: ` ["trace"] `

  - ` origin `: type ` string ` — How the trace came to be (NOTES/deploy-platform/observability.md 2.2). This beta gives `traceparent` (a caller's own trace: a turn of the SDKs' turn helper, or a harness's) or `call` (one call and its retries, or a trace made only by SDK versions that send no mark); the others come with the node's own spans. 

    - enum: ` ["turn","traceparent","inferred","run","call","ingested"] `

  - ` nested `: type ` boolean ` — false in this beta: spans are the trace's requests, listed flat in start order.

  - ` project_id `: type ` string `

  - ` app `: type ` string `; nullable — The `b3os.app` tag of the first sandbox that made a request in the trace; null outside a deploy.

  - ` deploy `: type ` string `; nullable

  - ` service `: type ` string `; nullable — The service name from that sandbox's `b3os.item` tag (`service/<name>`).

  - ` started_at `: type ` string `; format ` date-time `

  - ` ended_at `: type ` string `; format ` date-time `

  - ` duration_ms `: type ` number `

  - ` harness_ms `: type ` number ` — Time between the trace's first start and last end when no B3OS request was in flight.

  - ` status `: type ` string `

    - enum: ` ["ok","error"] `

  - ` counts `: type ` object `

    - Required fields: ` spans `, ` model_calls `, ` tool_calls `, ` errors `, ` dropped `

    - ` spans `: type ` integer `

    - ` model_calls `: type ` integer `

    - ` tool_calls `: type ` integer `

    - ` errors `: type ` integer `

    - ` dropped `: type ` integer ` — Spans the node dropped past its cap; always 0 in this beta (`truncated` says the 300-request read stopped early).

  - ` usage `: type ` array `

    - ` array item `: type ` object `

      - Required fields: ` unit `, ` qty `

      - ` unit `: type ` string ` — The usage unit (`infer.input_tokens`, `vision.page`, `sandboxes.vcpu_ms`).

      - ` qty `: type ` number `

  - ` sandboxes `: type ` array `

    - ` array item `: type ` object `

      - Required fields: ` id `, ` app `, ` deploy `, ` item `

      - ` id `: type ` string `

        - pattern: ` "^sbx_[0-9a-hjkmnp-tv-z]{26}$" `

      - ` app `: type ` string `; nullable — The sandbox's `b3os.app` tag; null outside a deploy, or when the sandbox could not be read.

      - ` deploy `: type ` string `; nullable — Its `b3os.deploy` tag.

      - ` item `: type ` string `; nullable — Its `b3os.item` tag (`service/harness`, `eval/answers`).

  - ` spans `: type ` array `

    - ` array item `: type ` object ` — One request of the trace, as the request log recorded it.

      - Required fields: ` request_id `, ` kind `, ` name `, ` product `, ` operation_id `, ` method `, ` path `, ` status `, ` status_code `, ` error_code `, ` source `, ` connection `, ` sandbox_id `, ` user_agent `, ` started_at `, ` offset_ms `, ` duration_ms `, ` phases `, ` usage `

      - ` request_id `: type ` string `

        - pattern: ` "^req_[0-9a-hjkmnp-tv-z]{26}$" `

      - ` kind `: type ` string ` — What the span is, from the request's product and operation.

        - enum: ` ["model","sandbox.exec","vision","render","action","routine","request"] `

      - ` name `: type ` string ` — `<product>.<operation>` (`vision.scrape`), or the path when the operation is not known.

      - ` product `: type ` string `; nullable

      - ` operation_id `: type ` string `; nullable

      - ` method `: type ` string `

      - ` path `: type ` string `

      - ` status `: type ` string ` — `error` for a 4xx or 5xx answer.

        - enum: ` ["ok","error"] `

      - ` status_code `: type ` integer `

      - ` error_code `: type ` string `; nullable

      - ` error_detail `: type ` string `; nullable — The request record's `error_detail`, when it has one (why a 4xx or 5xx failed).

        - maxLength: ` 200 `

      - ` source `: type ` string `

      - ` connection `: type ` string `

      - ` sandbox_id `: type ` string `; nullable

      - ` user_agent `: type ` string `; nullable

      - ` started_at `: type ` string `; format ` date-time `

      - ` offset_ms `: type ` number ` — Milliseconds from the trace's first request to this one's start.

      - ` duration_ms `: type ` number `

      - ` phases `: type ` array `

        - ` array item `: type ` object `

          - Required fields: ` name `, ` source `, ` duration_ms `

          - ` name `: type ` string `

          - ` source `: type ` string `

            - enum: ` ["edge","node"] `

          - ` duration_ms `: type ` number `

      - ` usage `: type ` array ` — The usage records charged to this request, summed by unit.

        - ` array item `: type ` object `

          - Required fields: ` unit `, ` qty `

          - ` unit `: type ` string ` — The usage unit (`infer.input_tokens`, `vision.page`, `sandboxes.vcpu_ms`).

          - ` qty `: type ` number `

  - ` truncated `: type ` boolean `

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 `<step>=<source>:<ms>`: `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
{
  "id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "object": "trace",
  "origin": "traceparent",
  "nested": false,
  "project_id": "prj_01m5t3pf8heewxt65ej3dm577y",
  "app": "research-agent",
  "deploy": "dep_01m6a2zq8x9hkqd3n7c5b4v2tw",
  "service": "harness",
  "started_at": "2026-11-07T10:00:00.010Z",
  "ended_at": "2026-11-07T10:00:01.122Z",
  "duration_ms": 1112,
  "harness_ms": 160.3,
  "status": "ok",
  "counts": {
    "spans": 2,
    "model_calls": 1,
    "tool_calls": 1,
    "errors": 0,
    "dropped": 0
  },
  "usage": [
    {
      "unit": "infer.input_tokens",
      "qty": 1830
    },
    {
      "unit": "infer.output_tokens",
      "qty": 212
    },
    {
      "unit": "vision.page",
      "qty": 1
    }
  ],
  "sandboxes": [
    {
      "id": "sbx_01m5t68q1b590rj801nbzsqzkk",
      "app": "research-agent",
      "deploy": "dep_01m6a2zq8x9hkqd3n7c5b4v2tw",
      "item": "service/harness"
    }
  ],
  "spans": [
    {
      "request_id": "req_01m5t4yg394wegr3j4y01qb363",
      "kind": "vision",
      "name": "vision.scrape",
      "product": "vision",
      "operation_id": "visionScrape",
      "method": "POST",
      "path": "/v1/vision/scrape",
      "status": "ok",
      "status_code": 200,
      "error_code": null,
      "source": "sandbox",
      "connection": "sandbox",
      "sandbox_id": "sbx_01m5t68q1b590rj801nbzsqzkk",
      "user_agent": "b3os-sdk-ts/0.1.1 node/24.11.0",
      "started_at": "2026-11-07T10:00:00.010Z",
      "offset_ms": 0,
      "duration_ms": 139.4,
      "phases": [
        {
          "name": "fetch",
          "source": "node",
          "duration_ms": 121.2
        },
        {
          "name": "total",
          "source": "node",
          "duration_ms": 138.8
        }
      ],
      "usage": [
        {
          "unit": "vision.page",
          "qty": 1
        }
      ]
    },
    {
      "request_id": "req_01m5t6d8ksbzrfxhqhzge06mqn",
      "kind": "model",
      "name": "infer.createChatCompletion",
      "product": "infer",
      "operation_id": "inferCreateChatCompletion",
      "method": "POST",
      "path": "/v1/infer/chat/completions",
      "status": "ok",
      "status_code": 200,
      "error_code": null,
      "source": "sandbox",
      "connection": "sandbox",
      "sandbox_id": "sbx_01m5t68q1b590rj801nbzsqzkk",
      "user_agent": "openai-node/5.23.0",
      "started_at": "2026-11-07T10:00:00.310Z",
      "offset_ms": 300,
      "duration_ms": 812,
      "phases": [
        {
          "name": "ttft",
          "source": "node",
          "duration_ms": 127.9
        },
        {
          "name": "total",
          "source": "node",
          "duration_ms": 811.6
        }
      ],
      "usage": [
        {
          "unit": "infer.input_tokens",
          "qty": 1830
        },
        {
          "unit": "infer.output_tokens",
          "qty": 212
        }
      ]
    }
  ],
  "truncated": false
}
```

### ` 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#<code>`.

    - 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/<name>`, `#path/<name>` or `#header/<name>` 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 `<step>=<source>:<ms>`: `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#<code>`.

    - 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/<name>`, `#path/<name>` or `#header/<name>` 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 `<step>=<source>:<ms>`: `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#<code>`.

    - 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/<name>`, `#path/<name>` or `#header/<name>` 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 `<step>=<source>:<ms>`: `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"
}
```

### ` 404 ` — No request of this trace in your project in the last 7 days (`trace_not_found`).

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#<code>`.

    - 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/<name>`, `#path/<name>` or `#header/<name>` 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 `<step>=<source>:<ms>`: `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#trace_not_found",
  "title": "Trace not found",
  "status": 404,
  "code": "trace_not_found",
  "detail": "No request of trace 4bf92f3577b34da6a3ce929d0e0e4736 in this project in the last 7 days",
  "instance": "req_01m5t4yg394wegr3j4y01qb363"
}
```

### ` 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#<code>`.

    - 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/<name>`, `#path/<name>` or `#header/<name>` 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 `<step>=<source>:<ms>`: `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 `<limit>;w=<window seconds>;name="<limit id>"` (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#<code>`.

    - 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/<name>`, `#path/<name>` or `#header/<name>` 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 `<step>=<source>:<ms>`: `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#<code>`.

    - 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/<name>`, `#path/<name>` or `#header/<name>` 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 `<step>=<source>:<ms>`: `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/traces/4bf92f3577b34da6a3ce929d0e0e4736' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'
```

### JavaScript

```javascript
const response = await fetch('https://beta-api.b3os.org/v1/traces/4bf92f3577b34da6a3ce929d0e0e4736', {
  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/traces/4bf92f3577b34da6a3ce929d0e0e4736', headers=headers)
print(response.json())
```