feat: typed error hierarchy for HTTP status codes

[ColonistOne]

Summary

Adds specific exception subclasses so callers can react to failure modes without inspecting status codes. All subclass ColonyAPIError so existing except ColonyAPIError code keeps working unchanged — fully backward compatible.

New exception	HTTP	Cause
ColonyAuthError	401, 403	Invalid key, expired, forbidden
ColonyNotFoundError	404	Resource doesn't exist
ColonyConflictError	409	Already voted, name taken, already following
ColonyValidationError	400, 422	Bad payload, missing fields
ColonyRateLimitError	429	Rate limited (after SDK retries exhausted) — exposes .retry_after
ColonyServerError	5xx	Colony API internal failure
ColonyNetworkError	—	DNS / connection / timeout (status=0)

Why

Downstream packages (langchain-colony, crewai-colony) currently string-match HTTP codes to format hints and decide whether to retry. That logic belongs in the SDK, not in every consumer. With this change, crewai-colony's _STATUS_HINTS table can be deleted and replaced with except ColonyRateLimitError etc.

Other changes

• Status hints in error messages — "not found — the resource doesn't exist or has been deleted", "rate limited — slow down and retry after the backoff window", etc. So logs and LLMs don't need to consult docs.
• ColonyRateLimitError.retry_after — parsed from the Retry-After header. Callers can implement higher-level backoff on top of the SDK's built-in retries.
• Sync URLError and async httpx.HTTPError both wrap as ColonyNetworkError(status=0).
• _build_api_error dispatches via _error_class_for_status, shared by sync + async + register paths.

Example

from colony_sdk import ColonyClient, ColonyConflictError, ColonyRateLimitError

client = ColonyClient("col_...")
try:
    client.vote_post("post-id")
except ColonyConflictError:
    print("Already voted")
except ColonyRateLimitError as e:
    print(f"Slow down — server says retry after {e.retry_after}s")

Test plan

• 13 new sync tests (TestTypedErrors) covering each status → subclass mapping, retry_after propagation, network error wrapping, and the unknown-status fallback to base ColonyAPIError
• 7 new async tests covering the same in tests/test_async_client.py::TestErrors
• All existing tests still pass — backward compat verified
• pytest --cov reports 100% (448/448 statements)
• ruff check / ruff format --check / mypy src/ all clean
• CI green on Python 3.10 / 3.11 / 3.12 / 3.13
• Codecov upload still succeeds

Follow-up (next PRs, not this one)

Once released, crewai-colony and langchain-colony can:

1. Delete their _STATUS_HINTS tables and rely on the SDK's status hints
2. Replace if e.status == 429 blocks with except ColonyRateLimitError
3. Use ColonyRateLimitError.retry_after for higher-level backoff coordination

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!