Summary
The SDK documentation promises generic equal-jitter retry handling with a 60-second wall-clock ceiling, but the public API edge uses a 120-second Cloud Armor rate-based ban and currently returns HTML 429 responses without Retry-After. Retrying through the 60-second SDK window cannot outlast that ban and may keep traffic active against the banned edge key.
Transferred from cognitum-one/api#97 after the API-owned documentation and OpenAPI contract were corrected, merged, and deployed.
Done looks like
- Root, Node, Python, and Rust SDK guidance distinguishes Cloud Armor HTML 429 from application JSON rate limits and budget caps.
- Edge HTML 429 is documented as non-retryable during the 120-second ban; callers are told to stop and wait at least 120 seconds.
- Budget-cap errors are explicitly non-retryable.
- If runtime clients currently auto-retry an HTML 429, add cross-language conformance coverage and correct the retry classifier rather than documenting unsafe behavior.
- Keep the three SDKs behaviorally aligned.
Live contract
- X-API-Key: 60 requests / 60 seconds per header value.
- Requests without X-API-Key, including Authorization Bearer API keys: 120 / 60 seconds per source IP.
- Exceed: 120-second edge ban, HTML 429, no Retry-After.
Refs: cognitum-one/api#97, cognitum-one/api#134.
Summary
The SDK documentation promises generic equal-jitter retry handling with a 60-second wall-clock ceiling, but the public API edge uses a 120-second Cloud Armor rate-based ban and currently returns HTML 429 responses without Retry-After. Retrying through the 60-second SDK window cannot outlast that ban and may keep traffic active against the banned edge key.
Transferred from cognitum-one/api#97 after the API-owned documentation and OpenAPI contract were corrected, merged, and deployed.
Done looks like
Live contract
Refs: cognitum-one/api#97, cognitum-one/api#134.