What
When the API refuses a request because a usage limit was reached, the api_error in the SDK can now carry an optional rate_limit_info field. The SDK is the Agent SDK, which lets programs run Claude Code. The field has the same shape as rate_limit_event and describes the limit that refused the request:
Why
Programs can show a user when the limit resets without having to pick that out of the error message text.
Names in the bundlerate_limit_infoapi_errorrate_limit_event
Documented inclaude-code/agent-sdk/python
The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.
Confirmed since
Anthropic's documentation has since written up rate_limit_event, on Claude Code changelog.
- Improved headless `rate_limit_event` usage-limit warnings to say whether the account has extra usage turned onchangelog see the edit
One source agreesOne thing we can check says the same as this entry.
Anthropic's documentation agrees
Anthropic's documentation has since written up rate_limit_event, on Claude Code changelog.