feat: configurable RetryConfig for transient-failure retries

[ColonistOne]

Summary

Adds a frozen RetryConfig dataclass that callers pass via:

ColonyClient(api_key, retry=RetryConfig(...))
AsyncColonyClient(api_key, retry=RetryConfig(...))

Field	Default	Notes
max_retries	2	Number of retries after the initial attempt. 0 disables retries.
base_delay	1.0	Base backoff in seconds. Nth retry waits base_delay * 2**(N-1).
max_delay	10.0	Cap on the per-retry delay (seconds).
retry_on	frozenset({429, 502, 503, 504})	HTTP statuses that trigger a retry.

The server's Retry-After header always overrides the computed delay.

Why

Downstream packages (langchain-colony, crewai-colony) currently re-implement retry logic on top of the SDK with their own RetryConfig clones. That logic belongs in one place — here. With this change they can delete their wrappers and just pass retry= through.

⚠️ Behavior change: 5xx gateway errors retried by default

Previously the SDK only retried 429s. It now also retries 502 Bad Gateway, 503 Service Unavailable, and 504 Gateway Timeout — these almost always represent transient infra issues that clear on retry.

500 Internal Server Error is intentionally not retried by default. It usually signals a bug in the request, not a transient failure, so retrying just amplifies the problem.

To restore the old 1.4.x behaviour:

ColonyClient("col_...", retry=RetryConfig(retry_on=frozenset({429})))

Internals

• _should_retry(status, attempt, config) and _compute_retry_delay(attempt, config, retry_after_header) helpers shared by sync + async _raw_request paths.
• _raw_request signature gains a separate _token_refreshed flag so the 401-refresh path doesn't consume the configurable retry budget. (Otherwise a 401 followed by a 429 storm would only get max_retries - 1 retries, which is surprising.)
• ColonyClient / AsyncColonyClient gain a retry attribute — the RetryConfig instance, defaulting to RetryConfig() when None passed.

Examples

from colony_sdk import ColonyClient, RetryConfig

# Disable retries entirely — fail fast
client = ColonyClient("col_...", retry=RetryConfig(max_retries=0))

# Aggressive for a flaky network
client = ColonyClient(
    "col_...",
    retry=RetryConfig(max_retries=5, base_delay=0.5, max_delay=30.0),
)

# Also retry 500 in addition to defaults
client = ColonyClient(
    "col_...",
    retry=RetryConfig(retry_on=frozenset({429, 500, 502, 503, 504})),
)

Test plan

• 14 new sync tests (TestRetryConfig) covering: defaults, frozen-ness, custom config wiring, max_retries=0, custom max_retries, default 503 retry, default 500 no-retry, custom retry_on, exponential backoff math, max_delay capping, Retry-After override, mixed 429/503 retry-then-success, token refresh not consuming retry budget
• 7 new async tests (TestAsyncRetryConfig) mirroring the same scenarios
• All existing tests still pass — fully backward compatible API
• Package coverage stays at 100% (463/463 statements)
• ruff check / ruff format --check / mypy src/ all clean
• CI green on Python 3.10 / 3.11 / 3.12 / 3.13

Follow-up (next PRs, not this one)

After release, crewai-colony and langchain-colony can delete their custom RetryConfig dataclasses and pass the SDK's RetryConfig straight through to the underlying client.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!