docs: flag cache-window plugin pinning and on-chain submission race

Two subtle behaviors that aren't bugs but bite operators and plugin authors:

- Mutation hooks (onBeforeApiCall, onAfterApiCall, onBeforeSign) only fire on
  the first request in each cache TTL window. Cached hits skip them. Heartbeat
  / counter / alerting work should go in onResponseSent or onHttpRequest, which
  fire on every request.

- Cached responses are byte-identical (same data, signature, timestamp), so on
  every on-chain submission past the first the verifier reverts with "Already
  fulfilled" and the submitter eats gas. For endpoints whose consumers race to
  fulfill on-chain, set a short maxAge or skip caching entirely.

No code changes — just lifting these from the audit notes into the public docs
where plugin authors and operators will see them.

Author: andreogle

book/docs/config/apis.md

@@ -153,6 +153,17 @@ cache:
 response until the TTL expires. A cached response replays the same signature and timestamp, so within `maxAge` every
 caller (and every on-chain submission) gets the identical signed payload.
 
+:::warning On-chain race within the cache window
+Because every caller in a TTL window receives the **byte-identical** signed response, only the first on-chain submission
+through `AirnodeVerifier` succeeds. The verifier's `fulfilled[]` mapping treats subsequent submissions of the same
+`(endpointId, timestamp, data)` as replays and reverts with `"Already fulfilled"` — the second and third callers pay gas
+for a failed transaction.
+
+For endpoints whose consumers race to submit on-chain (price feeds, single-fulfillment auctions), set a short `maxAge`
+(e.g. 1000ms) or omit `cache` entirely so each caller gets a fresh signature. Caching is most useful for off-chain
+verification flows or endpoints with a single intended on-chain submitter.
+:::
+
 ## Endpoint-level fields
 
 Each endpoint describes one upstream API route:

book/docs/config/plugins.md

@@ -84,6 +84,20 @@ Guidelines:
 Plugins run in the order they are declared. For mutation hooks (`onBeforeApiCall`, `onAfterApiCall`, `onBeforeSign`),
 each plugin receives the output of the previous one.
 
+## Caching interaction
+
+The HTTP response cache (`apis[].cache.maxAge` or `endpoints[].cache.maxAge`) stores the entire signed response — data,
+signature, and timestamp — for the TTL window. Cached responses bypass the upstream API call, which also bypasses every
+hook from `onBeforeApiCall` onward:
+
+- `onBeforeApiCall`, `onAfterApiCall`, `onBeforeSign` — **only fire on the first request in each cache window**. Cached
+  hits within the TTL never invoke them.
+- `onHttpRequest`, `onResponseSent`, `onError` — fire on every request, cached or not.
+
+If your plugin tracks per-request signal (heartbeats, counters, alerting), put that work in `onResponseSent` or
+`onHttpRequest`. Don't rely on the mutation hooks to run once per HTTP request — they run once per upstream API call,
+which can be much rarer.
+
 ## Plugin name
 
 There is no `name` field in the config. The plugin's exported `name` (from its default export, or from the object its