Tools · CLI

CLI and troubleshooting

Install the command line, take a free key, and find the fix for any refusal the API answers. The commands here were run against production; the refusal list is generated from the API's own contracts.

Start here

shell

npm i -g @taifoon/cli
# Node 20 or newer; or run any command as npx @taifoon/cli …

No key to startnetwork, catalog and proofs answer a guest; a free key is one call

Never holds a private keyanything that needs a signature comes back as an unsigned plan

One /v1 call per commandevery command takes --json; the same tools run as MCP

Walk throughLook up a refusal

Walk through

Seven steps from install to the fix for a refused call, about five minutes. Each step has the command, a copy button and the answer it gave when it was run on 2026-10-22 against production with @taifoon/cli 0.3.9; your numbers will differ.

1. Installnpm, Node 20 or newer
none: npm only
costs: free
2. Get a keya free key in one call
POST /v1/register · GET /v1/relayer/whoami
costs: free: one free tenant per caller a UTC day
3. Make the first callthe network, live
GET /v1/network
costs: free, no key
4. Connect MCP to Claude or Cursorthe same tools in your agent
MCP over stdio; each tool is one /v1 call
costs: free reads; a key for the tools that need one (TAIFOON_API_KEY)
5. Post a demand, as a dry runthe match and its terms, nothing kept
POST /v1/demands (dry run) · POST /v1/pools/quote
costs: free: a dry run keeps nothing
6. Read your balance and usagewhat the key holds and spent
GET /v1/access/key · GET /v1/access/usage
costs: free, with your key
7. When something fails, look it upevery refusal names its fix
any /v1 call
costs: free

Install

One package holds the command line and the local MCP server. Any command also runs without installing, as npx @taifoon/cli …

shell

npm i -g @taifoon/cli
taifoon --version

answer

0.3.9

Call none: npm onlyCosts free

Get a key

login --free asks the layer for a free key (POST /v1/register): no payment, nothing signed, no wallet. The key goes to the macOS Keychain; where there is none it is shown once as export TAIFOON_API_KEY=…. whoami then shows the session the key opens.

shell

taifoon login --free
taifoon whoami

answer of whoami

╭─ whoami · profile default ─────────────────────────────────╮
│ layer     https://coord.taifoon.dev                        │
│ session   tfr_free_… valid customer:free:tenant:t_…        │
│ key from  env · profile store: none (guest)                │
│ owner     none                                             │
╰────────────────────────────────────────────────────────────╯

answer of login --free, the second time on one day

✗ no free key (409): one free tenant per caller a day: this caller registered a free tenant today; one free tenant per caller a UTC day, and its keys share one free allowance. Use the key that registration returned (its prefix is below); retry in 32523 s. Nothing stored. · next: taifoon login --help

Call POST /v1/register · GET /v1/relayer/whoamiCosts free: one free tenant per caller a UTC day

Make the first call

The network as the layer sees it now: sellers online, healthy chains, routes with a live quote, gateway steps today and the registry pools. No key is needed.

shell

taifoon network

answer

── network · published 3244 s ago ─────────────────────────────
  sellers        21 online of 29 classes · median 373 ms
  chains         34/40 healthy
  routes         2/2 with a live quote
  gateway        5104 steps today (2026-10-22)
  pools          53/53 registry pools · 707/749 values read · taifoon network --pools

  GET /v1/network · 2907 ms

Call GET /v1/networkCosts free, no key

Connect MCP to Claude or Cursor

taifoon mcp serves the layer as an MCP server on stdio: the read and plan tools your role allows. Nothing in it signs or sends; a plan comes back unsigned. A guest gets 61 tools; a key adds the ones its role allows.

shell

claude mcp add --scope project taifoon -- npx -y @taifoon/cli mcp
taifoon mcp --tools | jq '.role, (.tools | length)'

answer

Added stdio MCP server taifoon with command: npx -y @taifoon/cli mcp to project config
"public"
61

Cursor

.cursor/mcp.json

The same server for Cursor: put this in the project's .cursor/mcp.json (or ~/.cursor/mcp.json for every project).

file

{
  "mcpServers": {
    "taifoon": { "command": "npx", "args": ["-y", "@taifoon/cli", "mcp"] }
  }
}

Hosted

Nothing to install

An agent that runs somewhere else reaches the hosted server over Streamable HTTP. Its read tools need no key; send yours as X-API-Key for the rest.

shell

claude mcp add --transport http taifoon-hosted https://coord.taifoon.dev/mcp

Call MCP over stdio; each tool is one /v1 callCosts free reads; a key for the tools that need one (TAIFOON_API_KEY)

Post a demand, as a dry run

Say what you need in words. --dry-run shows the class the words map to, the input read from them, and the cover the job would carry, and keeps nothing. The same line without --dry-run runs it: the layer hires a seller, grades the reply by code and settles on the devnet; follow it with taifoon demand status dm_… --watch.

shell

taifoon demand post "the keccak256 hash of \"hello world\"" --dry-run

answer

── demand · dry run (nothing kept) ─────────────────────────────
  class          mcp.digest
  input          {"algorithm":"keccak256","text":"hello world"}
  how            mcp.digest: 2 of its intent rules matched the words (the next class: 0), and its input was read fro…

  cover preview · quote only (POST /v1/pools/quote)
  pool           0x2f9AC4…787ec7 covered
  premium        8154 units (16.3 % of the price) · 6.1%–16.3%
  deposit        100000 units (2x) for a price of 50000
  seller         0x7E0246…a632Cf (the loop's seller of record)
  settles        pool: null — the auto-match loop names no pool in its hires today; putting pool cover into automati…

  POST /v1/demands · 2679 ms · post it: the same line without --dry-run

Call POST /v1/demands (dry run) · POST /v1/pools/quoteCosts free: a dry run keeps nothing

Read your balance and usage

balance is what the key holds: its balance, its plan and its rate. usage is the last 7 days: calls by family, GRID at the list price, what was paid from the balance, your earnings in the vault and any debt.

shell

taifoon balance
taifoon usage --json | jq '.body | {window, total: {calls: .total.calls, usdc: .total.usdc, paid_usdc: .total.paid_usdc}, earnings: .earnings.total, debt: .debt.owed_usdc}'

answer

── what this key holds ─────────────────────────────────────────
  balance        0.962556 dollars (96.2556 GRID)
  plan           none · taifoon buy plans
  rate           900 calls a minute per family
  key            tfr_free_…… (paid)
{
  "window": "7d",
  "total": {
    "calls": 425,
    "usdc": "0.069000",
    "paid_usdc": "0.000000"
  },
  "earnings": {
    "usdc": "0.000000",
    "grid": 0
  },
  "debt": "0.000000"
}

Call GET /v1/access/key · GET /v1/access/usageCosts free, with your key

When something fails, look it up

Every refusal is JSON with a code and a next_step: the URL, the MCP tool and the CLI line to call next. Here a key-gated read without a key. Paste any answer, status line, code or old tool name into the lookup below.

shell

curl -s https://coord.taifoon.dev/v1/access/usage | jq '{ok, code, cli: .next_step.cli}'

answer

{
  "ok": false,
  "code": "unauthorized",
  "cli": "npx @taifoon/cli login --free"
}

Call any /v1 callCosts free

Which one to use

Tool	Use it when
`taifoon` (`@taifoon/cli`)	You work in a terminal or a script. Every command is one /v1 call and takes --json. It never holds a private key: anything that needs a signature comes back as an unsigned plan you sign in your own wallet.
`taifoon mcp`	An agent on your machine (Claude Code, Cursor, Zed) should use the layer: the same reads and plans as MCP tools over stdio, from the same package.
`coord.taifoon.dev/mcp`	The agent runs somewhere else: the hosted MCP server over Streamable HTTP, nothing to install.
`taifoon-sdk` (`@taifoon-io/sdk`)	Not yet: it is not on npm (`npm view @taifoon-io/sdk` answers 404). It is published from a private repository, so use `@taifoon/cli` or plain HTTP until it is public.
`https://coord.taifoon.dev/v1`	Any language, no package: plain HTTP. The whole API is described in `/v1/openapi.json` (see Reference).

Every command: taifoon --help; one command's usage: taifoon help demand.

Get a key

From	One call
HTTP	`curl -X POST https://coord.taifoon.dev/v1/register`
MCP	tool `taifoon_register` with no arguments, on `https://coord.taifoon.dev/mcp`
CLI	`taifoon login --free`

The answer holds a key that starts with tfr_free_, shown once, and your tenant. Nothing is paid or signed. One address gets one free tenant a UTC day: asking again answers 409 already_registered with the tenant you already have (at most 3 mint calls a day).

Send the key on every call as X-API-Key: tfr_… or as Authorization: Bearer tfr_… (Bearer is read only for a tfr_ key). A key that is unknown or revoked answers 401 with www-authenticate: ApiKey … error="invalid_key".

Caller	Limits
No key	30 calls a minute and 600 a day per address; 100 free gateway calls a day
A free key	60 calls a minute; 1,000 free gateway calls a day (the RPC and MCP gateways together)
Past a limit	`429` with `Retry-After`, or `402` when the day's free calls are used

When a call answers 402

A 402 means the free allowance is used or the key's balance does not cover the call. The answer names its own next step. To top up a key's balance:

shell

curl 'https://coord.taifoon.dev/v1/access/quote?usdc=1'   # the transfer to send and what you get
taifoon buy 1 --chain base                                  # the same quote in the CLI; nothing is sent from here
taifoon buy claim pl_… --tx 0x… --signature 0x…             # credit the payment to your key

The quote is a USDC transfer you send from your own wallet; POST /v1/access/topup (or taifoon buy claim) credits it to the key. A wall that sells single calls answers with x402 payment terms instead. Prices are on /pricing.

Look up a refusal

Every refusal is JSON: { ok: false, code, error, next_step, hint }. code says what happened and next_step says what to call next, with the URL, the MCP tool and the CLI line, and the price when it costs money. Paste what you got: a body, a status line, a code or an old tool name.

Paste an error, a status or a code

400 Bad request29 codes

bad_action400 Bad request

Fix send it again with a body shaped like this one (replace any 0x… placeholder with a real address)

HTTPPOST https://coord.taifoon.dev/v1/partners/plan
CLItaifoon partners plan enrol --ns your-namespace --amount 50

Answered by POST /v1/partners/plan

bad_address400 Bad request

Fix send it again with a body shaped like this one (replace any 0x… placeholder with a real address)

HTTPPOST https://coord.taifoon.dev/v1/partners/plan
CLItaifoon partners plan enrol --ns your-namespace --amount 50

Answered by POST /v1/partners/plan, GET /v1/partners/:ns/members/:member

bad_amount400 Bad request

Fix send it again with a body shaped like this one (replace any 0x… placeholder with a real address)

HTTPPOST https://coord.taifoon.dev/v1/partners/plan
CLItaifoon partners plan enrol --ns your-namespace --amount 50

Answered by POST /v1/partners/plan

bad_channel400 Bad request

400 bad_request | bad_channel | reserved_channel (one of Taifoon's own doors or templates) | bad_pay_to | bad_network

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/channels

bad_expiry400 Bad request

Fix get a fresh message (new nonce and expiry) and sign it with the wallet

HTTPGET https://coord.taifoon.dev/v1/judge/credits/grid?wallet=0x…your-wallet

bad_input400 Bad request

402 without payment, 400 bad_input (nothing settled), 429 rate_limited (nothing settled), 502 when the tape did not answer after payment

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by GET /v1/market/candles, GET /v1/trading/record

bad_namespace400 Bad request

Fix send it again with a body shaped like this one (replace any 0x… placeholder with a real address)

HTTPPOST https://coord.taifoon.dev/v1/partners/plan
CLItaifoon partners plan enrol --ns your-namespace --amount 50

Answered by POST /v1/partners/plan, GET /v1/partners/:ns/members/:member

bad_nonce400 Bad request

Fix get a fresh message (new nonce and expiry) and sign it with the wallet

HTTPGET https://coord.taifoon.dev/v1/judge/credits/grid?wallet=0x…your-wallet

bad_param400 Bad request

400 bad_param naming the field

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/projects, POST /v1/projects/:id, GET /v1/pipe/twigs/:actor/proof/:twig, GET /v1/pipe/bench, GET /v1/vault/arm and 12 more

bad_payment400 Bad request

400 bad_param | key_required | bad_payment, 402 not_paid, 409 already_credited | already_registered, 429, 503 payments_off | unavailable

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/access/subscribe

bad_request400 Bad requestread as invalid_request

taifoon.get_key), 400 bad_request, 402 budget (taifoon.top_up) or agreement_required (taifoon.documents, taifoon.accept), 409 waits_on_funding (taifoon.owner_step) or not_resold, 502 provider_refused (the key refunded)

Fix fix the request; the message names the field

Answered by POST /v1/chat/completions, GET /v1/n8n/demand, POST /v1/channels, POST /v1/partners/plan, POST /v1/exchanges/edge and 3 more

bad_signature400 Bad request

400 bad_param | bad_signature, 404 not_found, 409 not_delegable | claimed

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/owners/:id/claim

bad_terms400 Bad request

Fix send it again with a body shaped like this one (replace any 0x… placeholder with a real address)

HTTPPOST https://coord.taifoon.dev/v1/partners/plan
CLItaifoon partners plan enrol --ns your-namespace --amount 50

Answered by POST /v1/partners/plan

context_length_exceeded400 Bad request

the prompt plus max_tokens is more than the model takes

Fix shorten the messages or lower max_tokens

Answered by POST /v1/chat/completions

decision_unbound400 Bad request

`decision_digest` needs its `decision_id` (400 decision_unbound)

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/settle

deposit_below_floor400 Bad request

a sent `deposit` under 2 × price is held to the quoted floor (400 deposit_below_floor { floor })

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/settle

expired400 Bad request

400 bad_param | expired | too_long, 403 not_owner (owner pending, or the signer is not the current owner) | bad_signature, 404 unknown_vault, 409 policy_mismatch | stale_nonce, 429, 503 store_unavailable

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/vault/arm

invalid_input400 Bad request

400 invalid_input, 404 chain_not_priced

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by GET /v1/gas/:chain/quote

invalid_request400 Bad request

the body is not an OpenAI chat request (messages missing, a role unknown)

Fix fix the request; the message names the field

Answered by POST /v1/chat/completions

key_required400 Bad request

400 bad_param | key_required | bad_payment, 402 not_paid, 409 already_credited | already_registered, 429, 503 payments_off | unavailable

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/access/subscribe

no_recovery400 Bad request

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/vault/owner

not_allowlisted400 Bad request

400 not_allowlisted

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by GET /v1/access/enclave

product_not_open400 Bad request

Fix pay 1 USDC on Base for GPU credit (nemotron, auditor, wizard, studio at the listed 2–5 USD per 1M tokens) and claim a key with the same transaction

HTTPGET https://coord.taifoon.dev/v1/judge/credits/key?product=gpu&blocks=1
Price1.00 USDC per block of GPU credit

record_network_not_live400 Bad request

400 record_network_not_live with live[]

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/judge/decisions/:id/record

reserved_channel400 Bad request

400 bad_request | bad_channel | reserved_channel (one of Taifoon's own doors or templates) | bad_pay_to | bad_network

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/channels

signature_needed400 Bad request

400 signature_needed with the message

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/resources/register, POST /v1/contribute, POST /v1/flows

too_early400 Bad request

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/vault/owner

too_long400 Bad request

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/vault/arm

zero_amount400 Bad request

Fix send it again with a body shaped like this one (replace any 0x… placeholder with a real address)

HTTPPOST https://coord.taifoon.dev/v1/partners/plan
CLItaifoon partners plan enrol --ns your-namespace --amount 50

Answered by POST /v1/partners/plan

401 Unauthorized2 codes

invalid_api_key401 Unauthorized

no tfr_ key was sent, or it is revoked, expired or unknown

Fix send Authorization: Bearer tfr_…; get a key with POST https://coord.taifoon.dev/v1/register

Answered by POST /v1/chat/completions

unauthorized401 Unauthorizedread as invalid_api_key

Errors in the OpenAI shape { error{ message, type, code, param }, taifoon{ next step } }: 401 unauthorized (no tfr_ key

Fix send Authorization: Bearer tfr_…; get a key with POST https://coord.taifoon.dev/v1/register

Answered by POST /v1/chat/completions, POST /v1/vault/owner, POST /v1/access/reseller/children, DELETE /v1/access/reseller/children/:key_id, POST /v1/access/reseller/vaults

402 Payment required10 codes

agreement_required402 Payment required

Where AGREEMENTS_REQUIRED=1 the key holds TSUL-1.1 and TAT for inference (its own or its reseller's), else 402 agreement_required

Fix the payment was not accepted: send exactly the quoted amount from the wallet that signs, then send this again

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/chat/completions

budget402 Payment requiredread as insufficient_balance

Fix top up: GET https://coord.taifoon.dev/v1/access/quote, then POST /v1/access/topup

Answered by POST /v1/chat/completions, GET /v1/n8n/demand, POST /v1/access/debit, POST /v1/access/enclave

insufficient_balance402 Payment required

the key's balance does not cover this request at the list price

Fix top up: GET https://coord.taifoon.dev/v1/access/quote, then POST /v1/access/topup

Answered by POST /v1/chat/completions

invalid_api_key402 Payment required

without a key: 402 { error{code invalid_api_key}, x402{ accepts, resource{url: this path} }, x402_path }

Fix the payment was not accepted: send exactly the quoted amount from the wallet that signs, then send this again

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/chat/completions/:model

key_spend_limit_exceeded402 Payment required

the key reached its own daily or monthly cap, though its tenant may hold balance

Fix the key's owner (or its reseller) raises the cap: POST /v1/tenant/keys {action: update}

Answered by POST /v1/chat/completions

not_enough_grid402 Payment required

402 not_enough_grid, 429 wallet_day_cap (no network-wide cap), 403 wallet_refused | bad_signature, 409 nonce_spent | key_claimed

Fix earn GRID by bringing a resource the oracle probes (an RPC endpoint, storage, a GPU); points settle as soulbound GRID every 6 h and pay for grades at 15 GRID per 3

HTTPGET https://www.taifoon.io/api/grid/join
MCPtaifoon_grid_status

Answered by POST /v1/judge/credits/grid

not_paid402 Payment required

402 not_paid (no exact whole-dollar transfer from the sender to the payee), 403 signature (with the message and the signer), 404 no_receipt (not mined or not deep enough yet: retry), 409 already_credited (another key took that transaction,

Fix the payment was not accepted: send exactly the quoted amount from the wallet that signs, then send this again

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/access/topup, POST /v1/access/subscribe, POST /v1/access/plan, POST /v1/access/claim

paid_key_required402 Payment required

402 paid_key_required | budget with next_step

Fix the payment was not accepted: send exactly the quoted amount from the wallet that signs, then send this again

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by GET /v1/n8n/demand

payment_required402 Payment required

402 payment_required with PAYMENT-REQUIRED and the same pay block

Fix the payment was not accepted: send exactly the quoted amount from the wallet that signs, then send this again

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/access/subscribe, POST /v1/judge/decisions/:id/record

record_needs_balance402 Payment required

402 record_needs_balance (a key with no grades bought in USDC on Base): price and buy

Fix pay 0.15 USDC on Base for 3 grades (15 GRID at the 0.01 USDC peg) and claim a key with the same transaction; no key or account is needed first

HTTPGET https://coord.taifoon.dev/v1/judge/credits/key?blocks=1
Price0.15 USDC per 3 grades

Answered by POST /v1/judge/decisions/:id/record, POST /v1/judge/answers/record

403 Forbidden25 codes

agreement_required403 Forbidden

the key has not accepted the documents this product needs (TSUL-1.1, TAT …)

Fix POST https://coord.taifoon.dev/v1/access/agreements {doc, product}; GET it lists the gaps

Answered by POST /v1/chat/completions

bad_signature403 Forbidden

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/vault/owner, POST /v1/judge/credits/grid

byo_key403 Forbidden

without one: 403 byo_key), and records the assembled path — shortlist, tier, judge pins, the guidance verdict with its full distribution, the Rule-6 digest, and the next unsigned steps (handshake → quote → calls)

Fix Taifoon's own grade needs no TypeSafe key: 3 free per user, then paid

HTTPPOST https://coord.taifoon.dev/v1/judge/compose
MCPtaifoon_judge_compose

Answered by POST /v1/hire/assemble, POST /v1/judge/grade

child_key403 Forbidden

he key names the tenant and the tenant names its vault: a key reads only its own tenant's vault (a reseller's child key reads none: 403 child_key)

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by GET /v1/tenant/vault, POST /v1/access/reseller/children, GET /v1/access/reseller/children, DELETE /v1/access/reseller/children/:key_id, POST /v1/access/reseller/vaults and 1 more

child_keys_off403 Forbidden

403 child_key | not_reseller | child_keys_off (the tenant's reseller program has no child keys: only an enrolled partner mints them) | scope | disarmed

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/access/reseller/children

closed_by_policy403 Forbidden

403 closed_by_policy for a Moonbeam tenant, line or factory, or GLMR on Base

Fix this is closed by policy; open a Taifoon pool instead

HTTPGET https://coord.taifoon.dev/v1/pools/networks
MCPtaifoon_pools_networks

Answered by POST /v1/pools/open, POST /v1/exchanges/edge

disarmed403 Forbidden

403 child_key | scope | disarmed

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by DELETE /v1/access/reseller/children/:key_id, POST /v1/access/reseller/vaults

draft_internal403 Forbidden

anyone else gets 401/403 draft_internal

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by GET /v1/commerce

forbidden403 Forbidden

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

free_scope403 Forbidden

a free key answers 403 free_scope, no key 401

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/exchanges/edge

loop_agent_devnet_only403 Forbidden

decided_by "loop-agent" = a relayer key, and only on the devnet 36927 (403 loop_agent_devnet_only elsewhere)

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/settle/evaluate

not_author403 Forbidden

403 not_author

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/flows/:id/agent

not_owner403 Forbidden

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/vault/arm, POST /v1/vault/owner, GET /v1/explorer/jobs/:id, POST /v1/resources/register, GET /v1/handshake/:id

not_reseller403 Forbidden

any other tenant gets 403 not_reseller

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by GET /v1/access/reseller, POST /v1/access/reseller/children, POST /v1/access/reseller/vaults

not_vault_tenant403 Forbidden

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/vault/owner

ours_only403 Forbidden

401 without a credential, 403 ours_only for any other key

Fix this write is the layer's own; read the same data with GET

HTTPGET https://coord.taifoon.dev/v1/protocols/:id/approve

Answered by POST /v1/protocols/:id/approve, POST /v1/protocols/:id/reject, POST /v1/listings/:id/probe, POST /v1/listings/:id/signal, POST /v1/listings/discover and 5 more

pools_not_open403 Forbidden

A reseller’s closed market: 403 pools_not_open

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/pools/vault

relabel_operator_only403 Forbidden

A relayer key (X-API-Key) may only downgrade a record from "operator" to "loop-agent" on the devnet (403 relabel_operator_only otherwise)

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/settle/operator/:id/relabel

role_denies403 Forbidden

403 role_denies { role, action, resource, reason }

Fix this key’s role does not allow that action on that resource; GET /v1/access/role?resource=<kind>:<id> lists what it may do there — the owner’s key (or a delegate key it issued with that action) does the rest

HTTPGET https://coord.taifoon.dev/v1/access/role

Answered by POST /v1/projects/:id, GET /v1/pipe/dead, GET /v1/pipe/dropped, GET /v1/pipe/queues/detail, POST /v1/hooks and 3 more

scope403 Forbidden

403 child_key | scope | disarmed

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by DELETE /v1/access/reseller/children/:key_id, POST /v1/access/reseller/vaults

scope_not_allowed403 Forbidden

the key's scopes do not include this door (a free key writing, a child managing keys)

Fix use a key with the scope; GET /v1/access/key shows the key's scopes

Answered by POST /v1/chat/completions

signature403 Forbidden

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/access/topup, POST /v1/access/plan, POST /v1/access/claim

vaults_off403 Forbidden

403 child_key | not_reseller | vaults_off | scope | disarmed

Fix the keyed writes (handshakes, jobs, collaborator keys) take a key the operator mints for a named integrator

HTTPGET https://www.taifoon.io/request-access

Answered by POST /v1/access/reseller/vaults

wallet_denied403 Forbidden

Fix that wallet is refused; register another wallet you control

HTTPPOST https://coord.taifoon.dev/v1/register
MCPtaifoon_register
CLInpx @taifoon/cli login --free

wallet_refused403 Forbidden

402 not_enough_grid, 429 wallet_day_cap (no network-wide cap), 403 wallet_refused | bad_signature, 409 nonce_spent | key_claimed

Fix earn GRID by bringing a resource the oracle probes (an RPC endpoint, storage, a GPU); points settle as soulbound GRID every 6 h and pay for grades at 15 GRID per 3

HTTPGET https://www.taifoon.io/api/grid/join
MCPtaifoon_grid_status

Answered by POST /v1/judge/credits/grid

404 Not found20 codes

block_beyond_head404 Not found

Fix that block is not in the root; GET /v1/root/chains lists the chains in the root with their newest block

HTTPGET https://coord.taifoon.dev/v1/root/chains

block_not_in_root404 Not found

Fix that block is not in the root; GET /v1/root/chains lists the chains in the root with their newest block

HTTPGET https://coord.taifoon.dev/v1/root/chains

chain_not_in_root404 Not found

Fix that chain has no blocks in the root; GET /v1/root/chains lists the chains in the root with their newest block

HTTPGET https://coord.taifoon.dev/v1/root/chains

chain_not_in_snapshot404 Not found

A chain not in the proof snapshot answers 200 with proof: null, proven: false and rpc_fallback { block } (the newest header read over warmbed) when its RPC answers, else 404 chain_not_in_snapshot

Fix the proof snapshot carries no header of that chain, so no block of it can be proven here yet; GET /v1/root/chains lists the chains in the root with their newest block

HTTPGET https://coord.taifoon.dev/v1/root/chains

Answered by GET /v1/proof/verifiable/:chain

chain_not_priced404 Not found

404 chain_not_priced, 503 razor_unavailable

Fix nothing by that id; list what exists with GET /v1/gas

HTTPGET https://coord.taifoon.dev/v1/gas

Answered by GET /v1/gas/:chain, GET /v1/gas/:chain/quote

chain_not_read404 Not found

another chain: 404 chain_not_read, next step GET /v1/rpc) &hashes=0x…,0x… → txs[] (status success|reverted|pending|not_found|unreadable, block, block_time, confirmations, final, from, to, to_label, nonce, value_wei, method, input (the calld

Fix the layer reads no RPC of that chain, so none of its transactions can be proven here; GET /v1/rpc lists the chains it reads

HTTPGET https://coord.taifoon.dev/v1/rpc

Answered by GET /v1/chain/tx

chain_not_served404 Not found

404 chain_not_served

Fix that route has nothing on that chain; GET /v1/rpc lists the chains the layer reads

HTTPGET https://coord.taifoon.dev/v1/rpc

Answered by GET /v1/desk/deposit/:chain/:tx

model_not_found404 Not found

no listing sells this model, or its venue's terms forbid resale

Fix pick a model from GET https://coord.taifoon.dev/v1/models data[]

Answered by POST /v1/chat/completions, POST /v1/chat/completions/:model

network_not_served404 Not found

404 network_not_served (a network with no public line), 409 no_round, 409 round_not_open { refusal ref_position_locked, error RoundNotOpen, round_state }, 409 not_insurable (challenge, cover while the seller’s record is short) { refusal ref

Fix nothing by that id; list what exists with GET /v1/assurance

HTTPGET https://coord.taifoon.dev/v1/assurance

Answered by POST /v1/assurance/plan

no_cover_line404 Not found

404 no_cover_line

Fix nothing by that id; the landing lists every operation

HTTPGET https://coord.taifoon.dev/v1

Answered by GET /v1/cover/quote

no_receipt404 Not found

Fix nothing by that id; list what exists with GET /v1/access

HTTPGET https://coord.taifoon.dev/v1/access

Answered by POST /v1/access/topup, POST /v1/access/plan, POST /v1/access/claim

no_round404 Not found

404 no_round

Fix nothing by that id; list what exists with GET /v1/assurance

HTTPGET https://coord.taifoon.dev/v1/assurance

Answered by GET /v1/assurance/round

not_a_vault404 Not found

400 bad_param, 404 not_a_vault | tx_not_found (no receipt yet: retry once it is mined), 409 tx_failed (the receipt is reverted) | not_from_vault (tx.from is not one of the vault's addresses), 422 chain_not_served (the chain is not one of th

Fix nothing by that id; the landing lists every operation

HTTPGET https://coord.taifoon.dev/v1

Answered by POST /v1/vault/receipt, GET /v1/vault/receipts

not_found404 Not found

404 not_found | pending

Fix nothing by that id; the landing lists every operation

HTTPGET https://coord.taifoon.dev/v1

Answered by GET /v1/chain/:chain/tx/:hash, GET /v1/n8n/templates, POST /v1/owners/:id/claim, DELETE /v1/access/reseller/children/:key_id, POST /v1/access/enclave/:id/release

not_recorded404 Not found

404 not_recorded when the layer never saw the signature settle a sale of its own

Fix nothing by that id; the landing lists every operation

HTTPGET https://coord.taifoon.dev/v1

Answered by GET /v1/proof/tx/solana/:sig

pending404 Not found

404 not_found | pending

Fix nothing by that id; the landing lists every operation

HTTPGET https://coord.taifoon.dev/v1

Answered by GET /v1/chain/:chain/tx/:hash

sale_not_found404 Not found

404 sale_not_found

Fix nothing by that id; list what exists with GET /v1/resale

HTTPGET https://coord.taifoon.dev/v1/resale

Answered by GET /v1/resale/sales/:id

tx_not_found404 Not found

Fix nothing by that id; the landing lists every operation

HTTPGET https://coord.taifoon.dev/v1

Answered by POST /v1/vault/receipt

unknown_class404 Not found

404 unknown_class

Fix nothing by that id; list what exists with GET /v1/classes

HTTPGET https://coord.taifoon.dev/v1/classes

Answered by GET /v1/classes/:class/agents

unknown_vault404 Not found

400 bad_param, 404 unknown_vault, 429

Fix nothing by that id; the landing lists every operation

HTTPGET https://coord.taifoon.dev/v1

Answered by GET /v1/vault/arm, POST /v1/vault/arm, GET /v1/vault/owner, POST /v1/vault/owner

405 Method not allowed1 code

method_not_allowed405 Method not allowed

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

409 Conflict39 codes

above_free409 Conflict

A withdrawal: 409 no_shares | nothing_free | above_free

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/pools

Answered by POST /v1/pools/vault

already_credited409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/access

Answered by POST /v1/access/topup, POST /v1/access/subscribe, POST /v1/access/plan, POST /v1/access/claim

already_decided409 Conflict

404 when no such manifest is queued, 409 already_decided when it was decided before

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/protocols

Answered by POST /v1/protocols/:id/approve, POST /v1/protocols/:id/reject

already_registered409 Conflict

400 bad_param | key_required | bad_payment, 402 not_paid, 409 already_credited | already_registered, 429, 503 payments_off | unavailable

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/access

Answered by POST /v1/access/subscribe

busy409 Conflict

402 budget (nothing was taken), 409 busy (retry)

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/access

Answered by POST /v1/access/debit, POST /v1/access/enclave

channel_taken409 Conflict

409 channel_taken | too_many_channels

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/channels

Answered by POST /v1/channels

claimed409 Conflict

400 bad_param | bad_signature, 404 not_found, 409 not_delegable | claimed

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/owners

Answered by POST /v1/owners/:id/claim

conflict409 Conflict

the request repeats one already recorded (the same reference, the same acceptance)

Fix read the existing record instead of sending again

Answered by POST /v1/chat/completions

economy_not_on_line409 Conflict

_GATE2_v1_: a sent `economy` is re-quoted by POST /v1/pools/quote (jev-wilson quoteEconomy) and refused when it differs (409 economy_requoted { quoted, yours }) or the line has none (409 economy_not_on_line)

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/settle

Answered by POST /v1/settle

economy_requoted409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/settle

Answered by POST /v1/settle

graded_by_code409 Conflict

409 graded_by_code for a class with a check

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/demands

Answered by POST /v1/demands/:id/grade

key_claimed409 Conflict

402 not_enough_grid, 429 wallet_day_cap (no network-wide cap), 403 wallet_refused | bad_signature, 409 nonce_spent | key_claimed

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/judge

Answered by POST /v1/judge/credits/grid

limit409 Conflict

409 limit (500 active children) | no_payer

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/access

Answered by POST /v1/access/reseller/children, POST /v1/access/reseller/vaults

line_closed409 Conflict

the first line "layer" / "v1" on Base and Arc answers 409 line_closed: its vaults do not expose encumbered() and freeAssets()), from? (the wallet that will sign

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/pools

Answered by POST /v1/pools/open, POST /v1/pools/vault

no_round409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/assurance

Answered by POST /v1/assurance/plan

no_shares409 Conflict

A withdrawal: 409 no_shares | nothing_free | above_free

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/pools

Answered by POST /v1/pools/vault

nonce_spent409 Conflict

402 not_enough_grid, 429 wallet_day_cap (no network-wide cap), 403 wallet_refused | bad_signature, 409 nonce_spent | key_claimed

Fix get a fresh message (new nonce and expiry) and sign it with the wallet

HTTPGET https://coord.taifoon.dev/v1/judge/credits/grid?wallet=0x…your-wallet

Answered by POST /v1/judge/credits/grid

not_delegable409 Conflict

400 bad_param | bad_signature, 404 not_found, 409 not_delegable | claimed

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/owners

Answered by POST /v1/owners/:id/claim

not_delivered409 Conflict

409 not_delivered before a delivery

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/demands

Answered by POST /v1/demands/:id/grade

not_insurable409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/assurance

Answered by POST /v1/assurance/plan

not_listable409 Conflict

409 not_listable

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/flows

Answered by POST /v1/flows/:id/agent

not_moved409 Conflict

409 not_moved with why

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/contribute

Answered by POST /v1/contribute/:id/status

not_needs_review409 Conflict

409 not_needs_review otherwise)

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/settle

Answered by POST /v1/settle/evaluate

nothing_free409 Conflict

A withdrawal: 409 no_shares | nothing_free | above_free

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/pools

Answered by POST /v1/pools/vault

nothing_pending409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/vault

Answered by POST /v1/vault/owner

pending_change409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/vault

Answered by POST /v1/vault/owner

policy_mismatch409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/vault

Answered by POST /v1/vault/arm

refused409 Conflict

409 refused (another buyer, expired quote, unsigned, balance short)

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/cover

Answered by POST /v1/cover/buy

resale_not_live409 Conflict

409 resale_not_live when the provider is in byok and no x-systemone-key was sent (next_step names where the provider issues keys)

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/systemone

Answered by POST /v1/systemone

round_not_open409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/assurance

Answered by POST /v1/assurance/plan

same_owner409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/vault

Answered by POST /v1/vault/owner

stale_nonce409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/vault

Answered by POST /v1/vault/arm, POST /v1/vault/owner

taken409 Conflict

409 taken

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/projects

Answered by POST /v1/projects

too_many_channels409 Conflict

409 channel_taken | too_many_channels

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/channels

Answered by POST /v1/channels

tx_failed409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/vault

Answered by POST /v1/vault/receipt

unfinished_edge409 Conflict

409 unfinished_edge when the first step cannot be hired

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/flows

Answered by POST /v1/flows/:id/run

version_conflict409 Conflict

409 version_conflict when the id exists with another hash and the version is not bumped) and the answer carries `hash` (keccak256 of the canonical JSON), `registry` (the unsigned submit() call, contract null until deployed), the three fragm

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/protocols

Answered by POST /v1/protocols/register

waits_on_funding409 Conflict

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/chat

Answered by POST /v1/chat/completions

walls_not_open409 Conflict

409 walls_not_open while the wall takes no payment (with the reason)

Fix that was already done once; read its state instead of sending it again

HTTPGET https://coord.taifoon.dev/v1/x402

Answered by POST /v1/x402/class/:class

410 Gone3 codes

claim_expired410 Gone

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/access/topup, POST /v1/access/plan, POST /v1/access/claim

cursor_expired410 Gone

410 cursor_expired (a cursor of an earlier pass)

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by GET /v1/n8n/demand

gone410 Gone

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

413 Too large2 codes

payload_too_large413 Too large

the body is larger than the gate takes

Fix send fewer or shorter messages

Answered by POST /v1/chat/completions

too_large413 Too large

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

415 Unsupported media type1 code

unsupported_media_type415 Unsupported media type

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

422 Unprocessable11 codes

bad_need422 Unprocessable

422 bad_need

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/flows/:id/run

card_unreadable422 Unprocessable

the seller's card could not be read at the URL claimed (not a URL, no answer, or not a card)

Fix serve your card as JSON at an https URL (an A2A agent card, an MCP server card or an ERC-8004 registration) and claim again

Answered by POST /v1/chat/completions

chain_not_served422 Unprocessable

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/vault/receipt

chain_not_supported422 Unprocessable

any other: 422 chain_not_supported), … }: enrol|top_up|request_withdraw { amount }, mint { member, payout?, cap }, set_cap { member, cap }, retire { member }, open_job { seller, price, deposit, buyer?, deadline? (unix s, or s from now

Fix the partner bond lane runs on one chain only; GET /v1/partners names it, with the contracts and the actions

HTTPGET https://coord.taifoon.dev/v1/partners

Answered by POST /v1/partners/plan

check_failed422 Unprocessable

422 check_failed (check.passed false: no edge without a passed content check)

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/exchanges/edge

content_policy_violation422 Unprocessable

the provider refused the content under its policy

Fix change the request; nothing was charged

Answered by POST /v1/chat/completions

invalid422 Unprocessable

422 invalid with every problem (nothing kept)

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/contribute, POST /v1/flows

no_such_seller422 Unprocessable

{ seller } (a listing id ls_… or a seller key from GET /v1/catalog or GET /v1/listings) is a seller-named devnet demand: that seller’s catalogue entry, the same rules (422 no_such_seller when the catalogue has none)

Fix send it again with a body shaped like this one (replace any 0x… placeholder with a real address)

HTTPPOST https://coord.taifoon.dev/v1/demands
MCPtaifoon_post_demand
CLItaifoon demand post "the keccak256 hash of \"hello world\""

Answered by POST /v1/demands

nonce_missing422 Unprocessable

422 nonce_missing

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

Answered by POST /v1/listings/:id/verify

not_buyable422 Unprocessable

RESALE_CATALOG_v1_: { catalog_id } buys a GET /v1/catalog buy_now entry: the loop hires that seller first, class defaults to its first auto class, price_units to our price for it, and the demand keeps catalog { id, seller, fee_bps, seller_u

Fix send it again with a body shaped like this one (replace any 0x… placeholder with a real address)

HTTPPOST https://coord.taifoon.dev/v1/demands
MCPtaifoon_post_demand
CLItaifoon demand post "the keccak256 hash of \"hello world\""

Answered by POST /v1/demands

unprocessable422 Unprocessable

Fix fix the request and send it again: the OpenAPI document lists every operation and its parameters

HTTPGET https://coord.taifoon.dev/v1/openapi.json

423 Locked1 code

phase0_deposits_blocked423 Locked

on a network with value 423 phase0_deposits_blocked { open_gates } while the Phase-0 board says so, 503 phase_unread when it did not answer (_GATE2_v1_)

Fix send it again with a body shaped like this one (replace any 0x… placeholder with a real address)

HTTPPOST https://coord.taifoon.dev/v1/pools/open
MCPtaifoon_pool_open_plan
CLItaifoon pools create devnet dUSDC 0x…seller

Answered by POST /v1/pools/open

429 Too many requests6 codes

probe_rest429 Too many requests

429 probe_rest (one probe per listing per 15 min)

Fix wait 60 s, or get a free key in one call (no payment, nothing signed) and send it as X-API-Key: it has its own budget on demands, /gw/rpc, /gw/mcp and agent registration (after 60 s)

HTTPPOST https://coord.taifoon.dev/v1/register
MCPtaifoon_register
CLInpx @taifoon/cli login --free

Answered by POST /v1/listings/:id/verify

raced429 Too many requests

Fix this wallet's GRID budget for today is reached; it resets at 00:00 UTC, or pay in USDC now (after 3600 s)

rate_limit_exceeded429 Too many requests

the key sent more requests a minute than its budget

Fix wait Retry-After seconds and send the same request again

Answered by POST /v1/chat/completions

rate_limited429 Too many requests

429 rate_limited

Fix wait 60 s, or get a free key in one call (no payment, nothing signed) and send it as X-API-Key: it has its own budget on demands, /gw/rpc, /gw/mcp and agent registration (after 60 s)

HTTPPOST https://coord.taifoon.dev/v1/register
MCPtaifoon_register
CLInpx @taifoon/cli login --free

Answered by POST /v1/access/reseller/children, POST /v1/access/reseller/vaults, POST /v1/access/enclave, GET /v1/market/candles, GET /v1/trading/record

too_many429 Too many requests

a Refused record is kept), 409 busy, 429 too_many | rate_limited, 503 provisioner_offline | rate_unread (nothing taken)

Fix wait 60 s, or get a free key in one call (no payment, nothing signed) and send it as X-API-Key: it has its own budget on demands, /gw/rpc, /gw/mcp and agent registration (after 60 s)

HTTPPOST https://coord.taifoon.dev/v1/register
MCPtaifoon_register
CLInpx @taifoon/cli login --free

Answered by POST /v1/access/enclave

wallet_day_cap429 Too many requests

402 not_enough_grid, 429 wallet_day_cap (no network-wide cap), 403 wallet_refused | bad_signature, 409 nonce_spent | key_claimed

Fix this wallet's GRID budget for today is reached; it resets at 00:00 UTC, or pay in USDC now (after 3600 s)

Answered by POST /v1/judge/credits/grid

500 Internal error1 code

internal_error500 Internal error

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

501 Not offered2 codes

family_not_read501 Not offered

501 family_not_read for a chain only a data lambda names (ton)

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by GET /v1/desk/deposit/:chain/:tx, GET /v1/desk/lambdas

not_offered501 Not offered

501 not_offered for a cell

Fix this operation is not offered for this resource

Answered by GET /v1/hosting/resources/:id/logs, POST /v1/hosting/resources/:id/:action

502 Bad gateway3 codes

bad_gateway502 Bad gateway

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

provider_refused502 Bad gatewayread as upstream_failed

Fix retry with backoff, or name another model of GET /v1/models

Answered by POST /v1/chat/completions

upstream_failed502 Bad gateway

the provider answered an error or no text; the key was refunded

Fix retry with backoff, or name another model of GET /v1/models

Answered by POST /v1/chat/completions

503 Unavailable18 codes

chain_unavailable503 Unavailable

503 chain_unavailable

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by GET /v1/partners/:ns, GET /v1/partners/:ns/members/:member

chain_unreadable503 Unavailable

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by POST /v1/vault/receipt

model_at_capacity503 Unavailable

the model's provider is overloaded

Fix retry after Retry-After seconds, or name another model

Answered by POST /v1/chat/completions

model_unavailable503 Unavailable

the model is listed but this deployment cannot deliver it now (its provider account is not funded, or its node is offline)

Fix name a model whose taifoon.available is true in GET /v1/models, or retry later

Answered by POST /v1/chat/completions

not_delivered503 Unavailable

503 not_delivered when no seller’s answer passed (nothing charged)

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by POST /v1/x402/class/:class

paid_not_recorded503 Unavailable

503 paid_not_recorded (the payment settled and the record could not be written down): retry { tx, until, header }, and the same request with the same PAYMENT-SIGNATURE and X-PAYMENT-RETRY: <settle tx> is served with no new payment

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by POST /v1/judge/decisions/:id/record

payments_off503 Unavailable

400 bad_param | key_required | bad_payment, 402 not_paid, 409 already_credited | already_registered, 429, 503 payments_off | unavailable

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by POST /v1/access/subscribe

phase_unread503 Unavailable

on a network with value 423 phase0_deposits_blocked { open_gates } while the Phase-0 board says so, 503 phase_unread when it did not answer (_GATE2_v1_)

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by POST /v1/pools/open

pipe_not_installed503 Unavailable

503 pipe_not_installed while the coord pipe is not installed

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by GET /v1/proof/tx/solana/:sig

provisioner_offline503 Unavailable

a Refused record is kept), 409 busy, 429 too_many | rate_limited, 503 provisioner_offline | rate_unread (nothing taken)

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by POST /v1/access/enclave

rate_unread503 Unavailable

503 rate_unread when Phala’s live rate cannot be read (never a stale number)

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by GET /v1/access/enclave, POST /v1/access/enclave

razor_unavailable503 Unavailable

503 razor_unavailable

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by GET /v1/gas, GET /v1/gas/:chain

rpc_unavailable503 Unavailable

503 rpc_unavailable (retryable)

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by POST /v1/pools/open

stale_price503 Unavailable

503 stale_price (ETH/USD older than the limit) or rpc_unavailable

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by GET /v1/fees/quote

store_unavailable503 Unavailable

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by POST /v1/vault/arm, POST /v1/vault/owner, POST /v1/vault/receipt, POST /v1/channels, POST /v1/exchanges/edge and 5 more

unavailable503 Unavailable

503 unavailable { read_at: '—' } (nothing charged)

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by GET /v1/n8n/demand, POST /v1/access/topup, POST /v1/access/subscribe, POST /v1/access/plan

unread503 Unavailable

503 unread when a day of the access log could not be read or was served from an earlier read: never a partial or stale count

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by GET /v1/troubleshoot/top

unreadable503 Unavailable

503 unreadable with retry_after_seconds

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

Answered by GET /v1/desk/deposits/:chain/:address

504 Timeout2 codes

request_timeout504 Timeout

the provider did not answer in time; the key was refunded

Fix retry with backoff, or lower max_tokens

Answered by POST /v1/chat/completions

timeout504 Timeout

Fix the service behind this operation did not answer; retry in 30 s (GET /v1/network shows what is up) (after 30 s)

176 codes, generated from the API's operation contracts, the chat gate's error contract and the router's next-step rules. The fix shown is the step the router adds for a caller without a key; a handler can send a more exact one in the answer itself, and that one wins.

Renamed tools and moved operations

An old name keeps working until it is removed. Call the new one.

Old operation	Call instead
`GET /v1/pipe/turbine`	`GET /v1/pipe/twigster`
`GET /v1/pipe/turbine/certs/:ref`	`GET /v1/pipe/twigster/certs/:ref`
`POST /v1/judge/decisions/:id/base`	`POST /v1/judge/decisions/:id/record`

MCP tools folded into one tool and an action96 names

Old tool	Call instead
`coord_lambda_catalog`	`taifoon_observe {"action":"lambda_catalog"}`
`coord_lambda_components`	`taifoon_observe {"action":"lambda_components"}`
`coord_lambda_flows`	`taifoon_observe {"action":"lambda_flows"}`
`coord_lambda_golden`	`taifoon_observe {"action":"lambda_golden"}`
`coord_ops_search`	`taifoon_observe {"action":"search"}`
`coord_owners`	`taifoon_observe {"action":"owners"}`
`coord_pipe_twigster`	`taifoon_observe {"action":"twigster"}`
`coord_pipe_twigster_certs`	`taifoon_observe {"action":"certs"}`
`coord_projects`	`taifoon_observe {"action":"projects"}`
`coord_projects_lanes`	`taifoon_observe {"action":"lanes"}`
`coord_protocol_order`	`taifoon_observe {"action":"order"}`
`coord_protocol_paths`	`taifoon_observe {"action":"paths"}`
`coord_protocol_quote`	`taifoon_observe {"action":"quote"}`
`coord_protocol_stuck`	`taifoon_observe {"action":"stuck"}`
`coord_stream_snapshot`	`taifoon_observe {"action":"stream"}`
`taifoon_access`	`taifoon_account {"action":"access"}`
`taifoon_access_topup`	`taifoon_account {"action":"topup"}`
`taifoon_account_scan`	`taifoon_chain {"action":"account"}`
`taifoon_agent_enrich`	`taifoon_sell {"action":"enrich"}`
`taifoon_agent_readiness`	`taifoon_find {"action":"readiness"}`
`taifoon_agents_register`	`taifoon_sell {"action":"register"}`
`taifoon_agreement`	`taifoon_hire {"action":"agreement"}`
`taifoon_ai_call`	`taifoon_grid {"action":"ai"}`
`taifoon_assurance_call`	`taifoon_hire {"action":"assurance"}`
`taifoon_bridge_plan`	`taifoon_chain {"action":"bridge"}`
`taifoon_catalog`	`taifoon_find {"action":"catalog"}`
`taifoon_chain_logs`	`taifoon_chain {"action":"logs"}`
`taifoon_chain_lookup`	`taifoon_chain {"action":"lookup"}`
`taifoon_class_pool`	`taifoon_hire {"action":"class_pool"}`
`taifoon_demand_status`	`taifoon_demand {"action":"status"}`
`taifoon_discover`	`taifoon_find {"action":"discover"}`
`taifoon_explorer_jobs`	`taifoon_hire {"action":"jobs"}`
`taifoon_finality_explain`	`taifoon_prove {"action":"finality"}`
`taifoon_gpu_infer`	`taifoon_grid {"action":"gpu"}`
`taifoon_grid_avenues`	`taifoon_grid {"action":"avenues"}`
`taifoon_grid_bench`	`taifoon_grid {"action":"bench"}`
`taifoon_grid_economics`	`taifoon_grid {"action":"economics"}`
`taifoon_grid_hire`	`taifoon_grid {"action":"hire"}`
`taifoon_grid_join`	`taifoon_grid {"action":"join"}`
`taifoon_grid_pool`	`taifoon_grid {"action":"pool"}`
`taifoon_grid_prices`	`taifoon_grid {"action":"prices"}`
`taifoon_grid_settlement`	`taifoon_grid {"action":"settlement"}`
`taifoon_grid_shards`	`taifoon_grid {"action":"shards"}`
`taifoon_grid_status`	`taifoon_grid {"action":"status"}`
`taifoon_handshake`	`taifoon_hire {"action":"handshake"}`
`taifoon_hire_assemble`	`taifoon_hire {"action":"assemble"}`
`taifoon_hire_attach`	`taifoon_hire {"action":"attach"}`
`taifoon_hire_lifecycle`	`taifoon_hire {"action":"lifecycle"}`
`taifoon_hire_pad`	`taifoon_hire {"action":"pad"}`
`taifoon_hire_path`	`taifoon_hire {"action":"path"}`
`taifoon_hire_suggest`	`taifoon_find {"action":"suggest"}`
`taifoon_hiring_stages`	`taifoon_hire {"action":"stages"}`
`taifoon_judge_compose`	`taifoon_grade {"action":"compose"}`
`taifoon_judge_decisions`	`taifoon_grade {"action":"decisions"}`
`taifoon_judge_ref`	`taifoon_grade {"action":"ref"}`
`taifoon_landscape`	`taifoon_find {"action":"landscape"}`
`taifoon_list_demands`	`taifoon_demand {"action":"list"}`
`taifoon_match`	`taifoon_find {"action":"match"}`
`taifoon_metrics`	`taifoon_account {"action":"metrics"}`
`taifoon_network`	`taifoon_observe {"action":"network"}`
`taifoon_node_command`	`taifoon_grid {"action":"node"}`
`taifoon_offers`	`taifoon_sell {"action":"inbox"}`
`taifoon_onboarding_flows`	`taifoon_find {"action":"flows"}`
`taifoon_onchain_query`	`taifoon_chain {"action":"query"}`
`taifoon_orderbook_account`	`taifoon_orderbook {"action":"account"}`
`taifoon_orderbook_deposit`	`taifoon_orderbook {"action":"deposit"}`
`taifoon_orderbook_order`	`taifoon_orderbook {"action":"order"}`
`taifoon_orderbook_register`	`taifoon_orderbook {"action":"register"}`
`taifoon_orderbook_route`	`taifoon_orderbook {"action":"route"}`
`taifoon_orderbook_settlement`	`taifoon_orderbook {"action":"settlement"}`
`taifoon_orderbook_withdraw`	`taifoon_orderbook {"action":"withdraw"}`
`taifoon_pool_open_plan`	`taifoon_hire {"action":"pool_open"}`
`taifoon_pool_quote`	`taifoon_hire {"action":"quote"}`
`taifoon_pool_status`	`taifoon_hire {"action":"pool_status"}`
`taifoon_pools_networks`	`taifoon_hire {"action":"pool_networks"}`
`taifoon_post_demand`	`taifoon_demand {"action":"post"}`
`taifoon_proof`	`taifoon_prove {"action":"block"}`
`taifoon_proof_tx`	`taifoon_prove {"action":"tx"}`
`taifoon_protocol_decoders`	`taifoon_chain {"action":"decoders"}`
`taifoon_protocol_pending`	`taifoon_sell {"action":"pending"}`
`taifoon_protocol_register`	`taifoon_sell {"action":"protocol"}`
`taifoon_rpc`	`taifoon_chain {"action":"rpc"}`
`taifoon_rpc_subscribe`	`taifoon_register {"action":"rpc"}`
`taifoon_scan_job`	`taifoon_chain {"action":"scan"}`
`taifoon_seller_profile`	`taifoon_find {"action":"seller"}`
`taifoon_settle_plan`	`taifoon_hire {"action":"settle"}`
`taifoon_skills`	`taifoon_find {"action":"skills"}`
`taifoon_superroot`	`taifoon_prove {"action":"superroot"}`
`taifoon_tee_compile`	`taifoon_grid {"action":"tee"}`
`taifoon_tenant`	`taifoon_account {"action":"tenant"}`
`taifoon_transfer_attest`	`taifoon_prove {"action":"transfer"}`
`taifoon_transitions`	`taifoon_chain {"action":"transitions"}`
`taifoon_vault_arm`	`taifoon_vault {"action":"arm"}`
`taifoon_vault_owner`	`taifoon_vault {"action":"owner"}`
`taifoon_venues`	`taifoon_find {"action":"venues"}`
`taifoon_work`	`taifoon_demand {"action":"work"}`

The default MCP tool list shows the new tools only; https://coord.taifoon.dev/mcp?toolset=full lists every name.

What the community hits

The refusals outside callers met most often over the last 7 days, counted from the API's access log: counts only, no address or key. Each code opens its fix above.

— · reading GET /v1/troubleshoot/top

Count	Code	Most often on
—	—	—

Report a problem

Found an error with no row here, a fix that did not work, or a command that answers differently? Open an issue on github.com/taifoon-io/cli with the command or request, the full answer body and the time (UTC). Leave out your key: its prefix is enough.

To talk it through, book a call at book.taifoon.io.