Skip to content

Commit 7957ac9

Browse files
committed
Document empty response handling (204 No Content)
Add sections in apis.md and pull-and-push.md explaining how empty upstream responses are handled in raw mode (signed null) vs encoded mode (502 error).
1 parent 5882c37 commit 7957ac9

2 files changed

Lines changed: 29 additions & 0 deletions

File tree

book/docs/concepts/pull-and-push.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,23 @@ Raw mode is useful when the consumer needs the full JSON structure or when multi
6161
needed. The signature still proves the data came from this airnode, but the data itself is not ABI-encoded for on-chain
6262
use.
6363

64+
### Response (empty)
65+
66+
When the upstream API returns an empty body (e.g. HTTP 204 No Content), the behavior depends on encoding:
67+
68+
- **Raw endpoints** return `rawData: null` with a valid signature, attesting that the API returned no content.
69+
- **Encoded endpoints** return HTTP 502 because there is no data to extract and encode.
70+
71+
```json
72+
{
73+
"airnode": "0xd1e98F3Ac20DA5e4da874723517c914a31b0e857",
74+
"endpointId": "0xa1b2...endpoint-id-hash",
75+
"timestamp": 1711234567,
76+
"rawData": null,
77+
"signature": "0x1234...65-byte-ecdsa-signature"
78+
}
79+
```
80+
6481
## Push
6582

6683
Push is continuous. Airnode calls APIs on a background interval, signs the results, and stores them in an in-memory

book/docs/config/apis.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -411,6 +411,18 @@ endpoints:
411411
# No encoding -- raw JSON response is signed
412412
```
413413

414+
### Empty responses (204 No Content)
415+
416+
When the upstream API returns an empty body (e.g. HTTP 204), the behavior depends on the encoding mode:
417+
418+
- **Raw mode** — returns `rawData: null` with a valid signature. The signature covers `keccak256(toHex("null"))`,
419+
providing a verifiable attestation that the API returned no content.
420+
- **Encoded mode** — returns HTTP 502 with `"API returned no data to encode"`. There is no value to extract via
421+
JSONPath, so encoding cannot proceed.
422+
423+
Empty JSON objects (`{}`) behave similarly — raw mode signs them as-is, while encoded mode fails if the JSONPath finds no
424+
value at the configured path.
425+
414426
### Requester-specified encoding
415427

416428
Clients can control encoding by passing reserved parameters in their request body: `_type`, `_path`, and optionally

0 commit comments

Comments
 (0)