docs: audience-first sidebar, close consumer journey, expand troubleshooting

andreogle · andreogle · commit 79464252a82c · 2026-05-16T11:51:43.000-05:00
Phase 3 of the technical-writer audit — structural improvements.

- book/sidebars.ts: reorder so Operators and Consumers appear immediately
  after Introduction, before Concepts. Reframes the IA as audience-first
  rather than topic-first. Renamed "Airnode Operators" to "Operators" for
  parity with "Consumers", "Config" to "Config Reference". Moved
  v1-comparison from the top to the appendix-style tail.
- consumers/getting-started.md: add a "You're done (if you only need the
  value off-chain)" step before the on-chain section. Closes the
  off-chain consumer journey explicitly — Step 7 (on-chain) is now
  framed as optional rather than the implied conclusion.
- operators/publishing-endpoints.md (new): the operator's checklist for
  handing endpoint IDs, airnode address, and request contracts to
  consumers. Covers the parts of the operator-day-one workflow that
  weren't in operators/index.md (running the server) or
  operators/deployment.md (production runtime).
- operators/index.md "Next steps": link to the new publishing page.
- troubleshooting.md: expanded from 8 entries to 16. Added 429
  (rateLimit), 401 x402 verification flood, 402 payment-required, 503
  busy (maxConcurrentApiCalls), FHE encryption failures, plugin budget
  exhaustion, plugin cache-window non-firing, async store 404, async
  store 503, and CORS rejection — all of which were silently undocumented
  before.
diff --git a/book/docs/consumers/getting-started.md b/book/docs/consumers/getting-started.md
@@ -139,10 +139,24 @@ Raw responses need no decoding. Access the JSON directly:
 const ethPrice = rawData.ethereum.usd; // 3842.17
 ```
 
+## You're done (if you only need the value off-chain)
+
+At this point you have:
+
+- A verified `airnode` address (proves who signed it).
+- A decoded `value` (the price, the temperature, whatever the endpoint serves).
+- A `timestamp` (so you can decide if the value is fresh enough for your use case).
+
+That's the full off-chain consumer loop. Use the value in your app, run your own staleness check
+(`Date.now() / 1000 - timestamp < maxAgeSeconds`), and store or forward the signed payload if you want to prove
+provenance to a downstream system later — `(airnode, endpointId, timestamp, data, signature)` is a self-contained
+attestation that anyone can re-verify.
+
 ## Step 7: Submit on-chain (optional)
 
-Pass the signed data to an on-chain verifier contract. See [On-Chain Integration](/docs/consumers/on-chain) for contract
-examples using AirnodeVerifier.
+If you instead want a smart contract to consume the data, hand `(airnode, endpointId, timestamp, data, signature)` to
+`AirnodeVerifier.verifyAndFulfill(...)`. The verifier checks the signature and forwards to your callback. See
+[On-Chain Integration](/docs/consumers/on-chain) for contract examples.
 
 ## Choosing encoding at request time
 
diff --git a/book/docs/operators/index.md b/book/docs/operators/index.md
@@ -125,6 +125,8 @@ Bun automatically loads `.env` files from the working directory.
 
 ## Next steps
 
-- [Deployment](/docs/operators/deployment) -- run in production with systemd, Docker, or Docker Compose
-- [Config Reference](/docs/config) -- full configuration documentation
-- [Plugins](/docs/plugins) -- extend Airnode with custom hooks
+- [Publishing Endpoints](/docs/operators/publishing-endpoints) — what to share with consumers so they can call your
+  airnode
+- [Deployment](/docs/operators/deployment) — run in production with systemd, Docker, or Docker Compose
+- [Config Reference](/docs/config) — full configuration documentation
+- [Plugins](/docs/plugins) — extend Airnode with custom hooks
diff --git a/book/docs/operators/publishing-endpoints.md b/book/docs/operators/publishing-endpoints.md
@@ -0,0 +1,98 @@
+---
+slug: /operators/publishing-endpoints
+sidebar_position: 3
+---
+
+# Publishing Endpoints
+
+Once your airnode is running, consumers need three things to use it:
+
+1. The airnode's **base URL** (where to send `POST /endpoints/{endpointId}`).
+2. The **endpoint ID** for each endpoint they want to call.
+3. The **airnode address**, so they can verify signatures recover correctly.
+
+This page is the operator-side checklist for handing those out.
+
+## What an airnode address looks like
+
+The address is derived from your `AIRNODE_PRIVATE_KEY` (or `AIRNODE_MNEMONIC`). You can read it back at any time:
+
+```bash
+airnode address
+```
+
+```
+0xd1e98F3Ac20DA5e4da874723517c914a31b0e857
+```
+
+You can also fetch it from a running server:
+
+```bash
+curl http://localhost:3000/health
+```
+
+```json
+{
+  "status": "ok",
+  "airnode": "0xd1e98F3Ac20DA5e4da874723517c914a31b0e857"
+}
+```
+
+This address is what consumers pin as a trusted signer. Never let it drift — rotating the key means re-deriving every
+endpoint a consumer trusts.
+
+## Listing endpoint IDs
+
+On startup, the airnode logs every registered endpoint with its derived ID:
+
+```
+Plugin loaded: heartbeat (budget: 5000ms)
+Loaded 3 endpoint(s):
+  - CoinGecko/coinPrice    0x1c3e0fa5ac82e5514e0e9abac98e0b8e6c58b7bea12ae0393e4e4abe64ab9620
+  - CoinGecko/coinPriceRaw 0x9e1354c4ede00d01d99b610bfe6873ede803e0d598aeff820b51cc9d81a3568d
+  - WeatherAPI/currentTemp 0xa1b2...
+```
+
+The endpoint ID is a deterministic hash of the endpoint specification — change the path, method, parameters, or
+encoding and the ID changes too. See [Endpoint IDs](/docs/concepts/endpoint-ids) for what the hash commits to and why
+that matters for consumers.
+
+## Proving you're the API provider (optional)
+
+For a consumer to know that `airnode.example.com` is actually run by the operator of `api.example.com`, publish a
+[DNS identity record](/docs/security/identity-verification) (`_airnode.api.example.com` TXT). Consumers can verify the
+DNS record matches the address `/health` returned before pinning the address as trusted.
+
+## What to share with consumers
+
+A complete handoff covers, per endpoint:
+
+| Field                | Example                                                              | Why the consumer needs it                                    |
+| -------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Endpoint URL         | `https://airnode.example.com/endpoints/{endpointId}`                 | Where to POST.                                               |
+| Endpoint ID          | `0x1c3e0fa5ac82e5514e0e9abac98e0b8e6c58b7bea12ae0393e4e4abe64ab9620` | Pinned in their off-chain client or consumer contract.       |
+| Airnode address      | `0xd1e98F3Ac20DA5e4da874723517c914a31b0e857`                         | Recovers from the signature.                                 |
+| Parameter contract   | List of required + optional request parameters                       | So they can build a valid request body.                      |
+| Encoding shape       | e.g. `int256 × 1e18` for `$.ethereum.usd`                            | So they can `abi.decode` the result.                         |
+| Wildcard fields      | Which encoding fields are `'*'`, if any                              | They must supply matching `_type`/`_path`/`_times` per call. |
+| Auth                 | `free`, `apiKey` (and key value out-of-band), or `x402` payment      | So they can authenticate the request.                        |
+| Freshness expectation| e.g. "data is refreshed every 30s; reject >120s old"                 | Sets their on-chain or off-chain staleness threshold.        |
+| Cache TTL            | If `apis[].cache.maxAge` is set, what window                         | They should expect identical responses inside the window.    |
+
+The endpoint ID changes if you change the spec. Tell consumers up front whether the endpoint is considered
+stable — if you reserve the right to change `encoding.times` from `1e18` to `1e6`, say so. Any change invalidates the
+old ID and breaks consumers that hard-coded it.
+
+## Operator-side checklist
+
+Before announcing an endpoint:
+
+- [ ] The endpoint loads (`airnode start` prints its ID without errors).
+- [ ] The upstream API call works end-to-end (`curl` the airnode and inspect the signed response).
+- [ ] The signature recovers to the address you intend to publish.
+- [ ] If `auth` is `apiKey`, the key delivery channel is in place.
+- [ ] If `auth` is `x402`, the payment recipient address and chain are correct.
+- [ ] If consumers will read on-chain, a deployed `AirnodeVerifier` exists on their target chain
+      (the same one across chains is fine — there's no per-airnode registration).
+- [ ] If you're claiming ownership of the upstream API's domain, the
+      [DNS identity record](/docs/security/identity-verification) is published.
diff --git a/book/docs/troubleshooting.md b/book/docs/troubleshooting.md
@@ -127,6 +127,41 @@ value wins. If the endpoint has no `encoding` block at all, you'll get raw JSON
 **Fix:** Reduce the request payload size. If you need to send large bodies, check whether the parameters can be
 simplified.
 
+### `Too Many Requests` (429)
+
+**Cause:** You've exceeded `server.rateLimit.max` requests per IP within `server.rateLimit.window`. Each upstream API
+call costs the operator (metered API quotas), so the airnode caps per-IP throughput.
+
+**Fix:** Throttle your client. If you're behind a NAT or shared IP, ask the operator whether they trust an
+`X-Forwarded-For` header from your environment — if so, they can enable `rateLimit.trustForwardedFor` and the limit
+applies per real client.
+
+### `Too many x402 verification attempts — slow down` (401)
+
+**Cause:** You're an x402 client and you're submitting payment proofs faster than `server.rateLimit.x402.max` per
+`window`. This is a separate, stricter bucket from the global rate limit — each submitted proof triggers several
+chain-RPC reads, so unauthenticated flooders are throttled hard.
+
+**Fix:** Slow down proof submission. Only submit proofs for transactions you actually intend the airnode to verify;
+don't speculatively spam unverified `txHash` values.
+
+### `Payment required` (402)
+
+**Cause:** The endpoint has `auth.type: 'x402'` and you haven't supplied a valid payment proof.
+
+**Fix:** The 402 response body includes `airnode`, `endpointId`, `amount`, `token`, `network`, `recipient`, and
+`expiresAt`. Send the on-chain transfer, then retry with an `X-Payment-Proof` header containing
+`{ "txHash": "0x…", "expiresAt": <unix-seconds>, "signature": "0x…" }`. The signature is over
+`keccak256(encodePacked(airnode, endpointId, uint64(expiresAt)))` from the payer's EOA.
+
+### `Server busy` (503)
+
+**Cause:** The airnode is already running `settings.maxConcurrentApiCalls` upstream requests and your request waited
+its full timeout for a slot without getting one.
+
+**Fix:** Operator-side: raise `maxConcurrentApiCalls` if the upstream can handle it, or front the airnode with a CDN
+that caches frequent endpoints. Client-side: slow your request rate or add jitter.
+
 ## Upstream API errors
 
 ### `API call failed` (502)
@@ -152,6 +187,75 @@ response.
 **Fix:** Inspect the actual upstream response and adjust the `path` in the endpoint's encoding config. Common causes:
 the API changed its response format, a nested field was renamed, or the path uses the wrong separator.
 
+## FHE encryption errors
+
+### `FHE encryption failed` (502)
+
+**Cause:** The endpoint has an `encrypt` block, but the relayer rejected the encryption attempt. Common subcauses
+appear in the server log: a negative integer for an unsigned ciphertext (`euint*` types are unsigned), a value that
+overflows the chosen ciphertext type, or the relayer being unreachable.
+
+**Fix:** Check the airnode logs for the specific error. Common fixes: choose a larger `encrypt.type` (e.g.
+`euint256` instead of `euint64`); pin a non-negative encoding (`uint256` instead of `int256`); or verify
+`settings.fhe.rpcUrl` and `settings.fhe.apiKey` are correct.
+
+### `Endpoint requires FHE encryption but settings.fhe is not configured`
+
+**Cause:** An endpoint has `encrypt: { ... }` but `settings.fhe` is `'none'`.
+
+**Fix:** Either remove `encrypt` from the endpoint or set `settings.fhe` to a configured relayer block.
+Config-validation catches this at startup, so seeing it at runtime usually means the config was edited without
+restarting.
+
+## Plugin errors
+
+### `Plugin "X" budget exhausted` (request dropped, 403)
+
+**Cause:** A plugin defining a mutation hook (`onHttpRequest`, `onBeforeApiCall`, `onAfterApiCall`, `onBeforeSign`) has
+spent its full `timeout` budget on previous hook invocations within the same request. Mutation hooks are fail-closed —
+once the budget is gone, the request is dropped rather than being processed without the plugin's intervention.
+
+**Fix:** Operator-side: raise the plugin's `timeout` in `settings.plugins[].timeout`. Plugin-author side: pass each
+hook's `signal` to your `fetch` calls so cancellation actually propagates, and avoid unnecessary work in earlier hooks.
+
+### Plugin runs only on the first request in a cache window
+
+**Cause:** Not an error — by design. Cached responses bypass the upstream API call, which also bypasses the
+`onBeforeApiCall`, `onAfterApiCall`, and `onBeforeSign` hooks. Only `onHttpRequest`, `onResponseSent`, and `onError`
+fire on every request.
+
+**Fix:** If you need per-request signal, use `onResponseSent` or `onHttpRequest`. See
+[Plugins → Caching interaction](/docs/config/plugins#caching-interaction).
+
+## Async endpoint errors
+
+### `Request not found` (404) on `GET /requests/{requestId}`
+
+**Cause:** The request ID is wrong, or it's older than the async store's retention window (10 minutes for in-flight
+requests, 1 minute for completed/failed results). Finished results are evicted promptly so an unrelated request can
+take its slot.
+
+**Fix:** Poll within the retention window. If you waited longer, the result is gone — re-submit the request.
+
+### `Service Unavailable` (503) from a `mode: async` endpoint
+
+**Cause:** The async store is at its 100-entry cap and no slot can be safely evicted (every entry is still in-flight
+within its TTL or holds an unread result within its retention window).
+
+**Fix:** This indicates sustained submission rate exceeding the airnode's async capacity. Wait, retry, or have the
+operator review whether `mode: async` is appropriate for that workload.
+
+## CORS errors
+
+### Browser rejects response: `CORS policy: No 'Access-Control-Allow-Origin' header`
+
+**Cause:** The airnode's `server.cors` is configured with an `origins` allow-list that doesn't include your origin.
+Non-matching origins receive `Access-Control-Allow-Origin: null`, which browsers refuse.
+
+**Fix:** Operator-side: add your origin to `server.cors.origins`, or remove the `cors` block entirely (defaults to
+allowing every origin). Verify with `curl -i -H 'Origin: https://your-app.example' …` — the airnode echoes the matched
+origin back in the response header.
+
 ## General debugging
 
 **Check the logs.** Airnode logs every request with its endpoint ID, response status, and processing time. Set
diff --git a/book/sidebars.ts b/book/sidebars.ts
@@ -1,9 +1,22 @@
 import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
 
+// Audience-first navigation: a reader landing on the docs picks "I'm an
+// operator" or "I'm a consumer" first, then drills into concepts /
+// reference / security as needed. Concepts come after the audience tracks
+// because they make more sense once you know what you're building.
 const sidebars: SidebarsConfig = {
   docs: [
     'introduction',
-    'v1-comparison',
+    {
+      type: 'category',
+      label: 'Operators',
+      items: ['operators/index', 'operators/deployment', 'operators/publishing-endpoints'],
+    },
+    {
+      type: 'category',
+      label: 'Consumers',
+      items: ['consumers/getting-started', 'consumers/http-client', 'consumers/on-chain'],
+    },
     {
       type: 'category',
       label: 'Concepts',
@@ -18,24 +31,9 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: 'Guides',
-      items: ['guides/system-overview'],
-    },
-    {
-      type: 'category',
-      label: 'Config',
+      label: 'Config Reference',
       items: ['config/index', 'config/server', 'config/settings', 'config/apis', 'config/plugins'],
     },
-    {
-      type: 'category',
-      label: 'Airnode Operators',
-      items: ['operators/index', 'operators/deployment'],
-    },
-    {
-      type: 'category',
-      label: 'Consumers',
-      items: ['consumers/getting-started', 'consumers/http-client', 'consumers/on-chain'],
-    },
     'plugins',
     {
       type: 'category',
@@ -49,6 +47,7 @@ const sidebars: SidebarsConfig = {
     },
     'troubleshooting',
     'cli',
+    'v1-comparison',
     'roadmap',
   ],
 };
