Handling free API 429 errors without runaway retries

Separate request rate, token throughput, exhausted allowance and upstream capacity; add bounded retries and budget limits.

2026-11-03 · FreeTokenBox · Review method

A 429 may mean a short rate window, exhausted daily allowance or unavailable upstream capacity. Classify it before retrying.

Identify the unit

RPM/RPD count requests while TPM/TPD count tokens. A single long conversation can hit a token cap. Other services may count audio duration or compute units.

Record useful evidence

Log time, provider, model, status, error type and reset hints. Remove authorization headers, cookies, keys and private prompt text. With several services in the chain, record which layer failed.

Choose the next action

For a short rate window, lower concurrency and wait. For exhausted daily usage, stop the queue and show when it can resume. For capacity failures, use bounded retries or a separately approved alternative. A balance or budget failure will not be repaired by repeated requests.

Bound the workflow

Prefer Retry-After when provided. Otherwise use capped backoff with jitter, a maximum attempt count and a whole-task deadline. Stop when users cancel.

A timeout may occur after an operation has already happened. Workflows that write records or send messages need business-level idempotency before retrying; a model API response alone cannot prevent duplicates.

Test safely

Simulate temporary 429s, exhausted allowance and timeouts locally. Check queue shutdown, cancellation and user messages instead of deliberately overwhelming a real free service.

References

Groq limits, OpenRouter limits. Queueing recommendations are engineering guidance; provider-specific error meanings follow their documentation.