API Errors Explained: Rate Limits, Auth, Timeouts

Bots live and die by API calls — to exchanges, RPC providers, and LLMs — and APIs return errors. Understanding the common error types, what they mean, and how to handle them gracefully is essential for a reliable bot. This guide explains the API errors you'll encounter: rate limits, authentication failures, timeouts, and more, with the handling patterns that keep your bot resilient instead of crashing.

The difference between a fragile bot and a robust one is largely how it handles API errors. Errors are normal and constant; a bot that crashes on the first hiccup is broken by design. Let's make yours resilient.

TL;DR — The 30-second answer

• 429 (rate limit): too many requests too fast. Back off and retry.
• 401/403 (auth): bad key, wrong permissions, or IP not whitelisted.
• Timeouts: no response in time. Retry with backoff; don't hang.
• 5xx (server errors): the exchange/provider's problem. Retry; check status pages.
• The pattern: retry with exponential backoff, handle gracefully, log everything.
• Resilience is design: a bot that crashes on the first error is built wrong.

Common API errors

Rate limits (HTTP 429)

Every API limits how many requests you can make in a time window. Exceed it and you get a 429 Too Many Requests error. Bots hit this easily — an over-eager loop polling prices every second, or a burst of orders, can trip the limit. Handling:

• Respect the limits: know each API's rate limits and stay well under them. Don't poll more often than you need.
• Back off on 429: when you get rate-limited, wait before retrying — ideally honoring the Retry-After header if provided.
• Use exponential backoff: if retries keep failing, increase the wait each time (1s, 2s, 4s...) rather than hammering.
• Cache and batch: don't request data you already have; batch requests where the API supports it.

Rate limits are a common cause of intermittent bot failures — a bot that works in testing (low volume) breaks in production (higher volume) because it trips limits. Design for the rate limits from the start.

Authentication errors (401, 403)

A 401 Unauthorized or 403 Forbidden means the API rejected your credentials or permissions. The usual causes (and the most common OpenClaw problem overall — see our troubleshooting guide):

• Invalid or expired key: regenerate and update it.
• Wrong permissions: the key lacks the scope for the action (e.g. trying to trade with a read-only key). Re-scope it — trade-enabled, never withdrawal-enabled.
• IP not whitelisted: if you restricted the key to certain IPs and your bot's IP changed, it's rejected. Update the whitelist.
• Clock skew: some APIs require a timestamp; if your server's clock is off, signed requests fail. Sync your server time (NTP).

Auth errors are not transient — retrying won't help. Fix the credential/permission issue rather than retrying into the same wall.

Timeouts and network errors

Sometimes a request gets no response in time — a timeout — or the connection fails outright. These are often transient (a brief network blip, momentary provider slowness). Handling:

• Set sensible timeouts: don't let a request hang forever; set a timeout so the bot can react.
• Retry with backoff: transient timeouts usually resolve on retry. Use exponential backoff to avoid hammering.
• Idempotency for orders: critically — if you retry an order that may have actually succeeded, you risk a duplicate trade. Use idempotency keys or check order status before retrying order placement.
• Fallback providers: for RPC (Polygon, etc.), having a backup provider lets you switch if one is down.

The idempotency point is important: blindly retrying a timed-out order can double your position if the original actually went through. Always verify before retrying anything that changes state.

Server errors (5xx)

A 500/502/503 means the exchange or provider had an internal error — their problem, not yours. During high volatility, exchanges sometimes return these under load. Handling: retry with backoff (it's often transient), check the provider's status page (is there an outage?), and ensure your bot degrades gracefully — if you can't reach the exchange, the bot should wait and alert, not crash or make decisions on stale data. Major market events often coincide with exchange strain, exactly when you least want your bot confused.

The universal handling pattern

For robust API handling, wrap calls in a pattern that:

1. Tries the call with a sensible timeout.
2. Categorizes errors: transient (retry) vs permanent (don't retry, alert). A 429 or timeout is transient; a 401 is permanent.
3. Retries transient errors with exponential backoff up to a limit.
4. Verifies state before retrying state-changing calls (orders) to avoid duplicates.
5. Alerts on persistent or permanent failures via Telegram (see our guide) rather than failing silently.
6. Logs everything so you can diagnose patterns.

The honest verdict

API errors are not exceptional events to fear — they're a constant, normal part of running a bot, and handling them well is core to reliability. Know the categories: rate limits (429, back off), auth (401/403, fix don't retry), timeouts (retry with backoff, but verify before retrying orders), and server errors (5xx, the provider's problem, retry gracefully). Build the universal pattern — categorize, retry transients with backoff, verify state-changing calls, alert on persistent failures, log everything — and your bot becomes resilient instead of fragile. The bot that handles a rate limit or timeout gracefully keeps running; the one that crashes on the first 429 was never production-ready. Resilience isn't an add-on; it's how reliable bots are built.

Frequently asked questions

What to read next

• OpenClaw Troubleshooting
• Debugging a Trading Bot That Isn't Trading
• CCXT Skill Deep Dive
• OpenClaw for the Developer