agent read the rate-limit headers but ignored Retry-After - it retried immediately and the API banned the key for an...

TL;DR

Retry-After is an instruction, not a suggestion. When a 429 carries it, wait the full duration before the next request - retrying immediately is what turned a brief slowdown into an hour-long ban. After a ban, confirm the key's standing, add header-honoring backoff, and never let the client hammer a 429 again.

The query

agent read the rate-limit headers but ignored Retry-After  -  it retried immediately and the API banned the key for an hour

Steps

1. Confirm the key is banned and learn the terms

Check the provider's dashboard or error responses for the ban status and duration. Note what triggers it: repeated 429s without backing off is the classic cause. Do not keep testing with the banned key - every failed attempt can extend the ban.

Expected: the ban's scope and expiry time, from the provider, not from guessing.

2. Wait it out on a clean key or no key

Let the ban expire without traffic from the banned key. If the workload cannot wait, check whether the provider allows a secondary key - but do not use a second key to evade the limit the first key hit. The fix is behavior, not key rotation.

Expected: the ban lifts with zero requests attempted during the window.

3. Make Retry-After mandatory in the retry logic

Rewrite the 429 handler: when the response carries Retry-After, the client waits that long plus a small buffer before retrying, unconditionally. The header overrides any computed backoff. Log the wait so it is visible.

Expected: a 429 with Retry-After always produces a wait, never an immediate retry.

4. Back off per endpoint, not globally

Track rate-limit state separately for each endpoint. A 429 on the search endpoint should not pause the unrelated status endpoint, and one hot endpoint's backoff must not be averaged away across quiet ones.

Expected: per-endpoint backoff state; a 429 on one endpoint leaves others running.

5. Add a circuit breaker for repeated 429s

If 429s keep coming despite backoff, stop and alert instead of grinding through the ban threshold again. A breaker that trips after several consecutive 429s turns "banned for an hour" into "paused and paged."

Expected: the client halts with a clear alert before the provider has to ban it.

Use this when

• A key was banned or throttled hard after immediate 429 retries
• The generated code reads rate-limit headers but not Retry-After
• 429s escalate: first a slowdown, then a ban
• The retry logic treats 429 like a 503 and retries at full speed

Not for this skill when

• The ban came from terms-of-service abuse rather than rate limiting (different problem)
• The key is expired or revoked for non-rate reasons (check the dashboard)
• Backoff is already correct and 429s are rare (tune, do not rewrite)
• The provider never sends Retry-After (use pure exponential backoff instead)

Variant phrasings

retried immediately on 429 and got the key banned

The exact failure chain. Step 3 breaks it at the retry decision.

code read the rate-limit headers but not Retry-After

Reading the limit headers without honoring the wait instruction is the gap. Step 3 closes it.

Why it happens

The agent implemented the sophisticated-looking half of rate-limit handling - parsing the limit headers - and skipped the simple half: waiting when told to wait. Immediate retry feels like the responsive thing to do, and nothing in the code marked Retry-After as mandatory. The provider interpreted rapid-fire retries after an explicit wait instruction as abusive behavior, which is exactly what the ban mechanism is for. The client talked its way from a slowdown into a suspension.

Edge cases

• Retry-After in the past or zero: treat as "retry now, but count it." Do not spin; the breaker in step 5 still applies.
• Retry-After as an HTTP date versus seconds: parse both forms. Misparsed dates cause either infinite waits or immediate retries.
• Ban applies to the account, not just the key: rotating keys does not help and may look like evasion. Step 1's check of scope matters.
• Provider bans without any 429 warning: then the first signal IS the ban. The breaker cannot help; keep request rates conservative from step 1's empirical limits.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_fhXscH6hEJcir4YkuXDncQ