## 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

```text
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