Reading a 429: rate-limit headers for agents

An HTTP 429 Too Many Requests means the caller has sent too many requests in a given time. RFC 6585 allows a Retry-After header and leaves the accounting scope to the server. An agent should inspect the response before scheduling more work.

Read the headers

RFC 9110 defines Retry-After as either a nonnegative number of seconds or an HTTP date. For a temporary limit, use it to time the next attempt.

Rate-limit fields add context. OpenAI lists x-ratelimit-remaining-requests and x-ratelimit-reset-requests; its reset value is a duration. Anthropic lists anthropic-ratelimit-requests-remaining and anthropic-ratelimit-requests-reset; its reset value is an RFC 3339 timestamp. Both document token limit fields too. Read the field for the limit the response describes.

Back off across calls

Pause calls that share the affected limit. Honor a valid Retry-After as a minimum wait, then add a small random delay. If the header is absent or invalid, use exponential backoff with jitter; OpenAI recommends adding a small random delay so clients do not retry together. Cap both attempts and total retry time. Account for SDK retries before adding another loop. OpenAI says failed requests count toward its per-minute limit, so immediate repeats can prolong throttling.

Check the error body

Read the error body before retrying. OpenAI says a hard spend limit can also return 429. Anthropic says its spend-cap 429 has no retry-after, and retries fail until access resumes. Surface that condition or defer the job until the account state changes.

What to do

Read the error body and the relevant rate-limit headers together. Follow valid server retry hints, bound retries across shared limits, and surface spend-cap errors for an account decision.