8. Caching, ETags & rate limits
8.1 ETag & conditional GET
Every 200 carries a weak ETag of the form W/"<16-hex>" (SHA-256 of the response body, first 8 bytes, hex-encoded) and Cache-Control: public, max-age=3600.
The ETag is deterministic — identical backing data always produces the same ETag. Replay it on subsequent requests via If-None-Match to skip transferring an unchanged body:
curl -i -H "X-API-Key: bcp_<your_secret_key>" \
-H 'If-None-Match: W/"0123456789abcdef"' \
"https://api.bonafide.ai/api/v3/content/HO-XXXXXXXXXXXX/faq.json"
# → HTTP/1.1 304 Not Modified
# → ETag: W/"0123456789abcdef"
# → Cache-Control: public, max-age=3600
# (empty body)Both ?includePropertyId=true and ?includeCategory=true produce a different response body and therefore a different ETag. Store one ETag per (entityId, includePropertyId, includeCategory) triple and replay only the matching one — a client that toggles either flag will never receive a stale 304.
8.2 Rate limits
Per-API-key hourly limits are enforced by Bonafide. Default is 1,000 requests per hour; partner-specific overrides are configured at key issuance time (your key is sized for your nightly bulk sync plus ad-hoc PDP-level refreshes). When exceeded, the response is 429 with three quota headers:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests per hour allowed for the key. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Seconds until the window resets. |
Apply exponential backoff on 429; do not retry immediately. The same backoff/retry schedule applies to 5xx responses (including 503).
8.3 Payload-size guards
- Entity-count ceiling: a bulk
@graphresponse is capped at a configured number of entities (default 1,000). - Body-byte ceiling: the serialized response is capped at a configured byte size (default 10 MB).
When either guard fires, the endpoint returns 413 with the fallbackUrlPattern field set to /api/v3/content/{entityId}/faq.json. Switch to per-entity fetches using that pattern; the same authentication and caching rules apply.