Handling free API 429 errors without runaway retries
Separate request rate, token throughput, exhausted allowance and upstream capacity; add bounded retries and budget limits.
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.