Timeouts, rate limits and API key safety
This article covers what to do about timeouts and rate limits, and how to keep your API keys safe.
Timeouts
- Stream long outputs. Streaming (
"stream": true) returns output as it is generated, so you wait less and the request is less likely to be cut off by a network or proxy. - Use a longer client timeout. For non-streaming requests, 10 minutes or more. Claude Code uses
API_TIMEOUT_MS; SDKs usually have atimeoutparameter. - Timeouts mid-stream. During a stream the server sends a keep-alive about every 10 seconds; if the upstream produces no output for about 3 minutes, the request ends with a timeout error. Just retry.
Rate limits (429)
A 429 means the request cannot be handled right now. Common causes:
- too many requests in a short time, or too many at once;
- the upstream is temporarily busy;
- the key’s quota is used up (error code
API_KEY_QUOTA_EXHAUSTED).
What to do:
- Wait and retry. If the response has a
Retry-Afterheader, wait that many seconds. - Use exponential backoff in code: wait 1 second the first time, double it each time, and cap the number of retries.
- Do not fire large numbers of concurrent requests.
- If the key’s quota is used up, adjust it in the console or create a new key.
Keep your API keys safe
- Keep keys out of code. Pass them through environment variables. Do not commit keys to a repository or put them in front-end web pages.
- Use separate keys. Give each tool or device its own key, so a problem means disabling only one.
- Watch plain-text config files. Keys in files such as Claude Code’s
settings.jsonare plain text. Do not share or upload these files. - Disable a leaked key right away. Disable or delete it in the console, create a new one, and check usage records for unusual calls. Changing your password does not revoke existing keys.
- Send keys in headers. Do not put keys in URL query parameters; such requests are rejected.