Skip to content

P1 docs: prevent retries into api.cognitum.one 120-second edge bans #161

Description

@proffesor-for-testing

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions