# Stop the agent escalating to a human when it misreads a 429 as permanent auth failure

## TL;DR
A 429 means slow down, not give up. Classify errors before acting: 429 and 5xx are retryable with backoff, 401 and 403 are auth failures that may need a human. Escalating on a 429 burns human attention on a problem that a 60-second wait would have solved.

## The problem
```text
okta users api: 429 Too Many Requests, retry-after: 30
agent logic: non-200 then "authentication failed permanently" then paged the on-call admin
reality: credentials fine, budget refilled 30 seconds later
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=agent escalated to human misreading 429 as permanent auth failure"
```

## Fix it

### Step 1: Build an error classification table

Map status codes to handling: 429 means backoff and retry, 5xx means retry with backoff, 401 means refresh credential then retry once, 403 means stop and escalate, 400 means stop and fix the request. The agent consults this table; it never improvises.

Expected: every API error has exactly one handling path, written down.

### Step 2: Honor retry-after on 429

When a 429 arrives, sleep for the retry-after duration (or exponential backoff if none is given), then retry the same request. Only after the retry budget is exhausted does the error escalate.

Expected: transient rate limits resolve without any human involvement.

### Step 3: Separate auth failures from rate limits explicitly

A 401 after a working session means the credential expired - refresh it. A 429 with a valid credential means the budget is spent - wait. Log which one the agent decided and why.

Expected: the run log shows the classification decision for every error, auditable later.

### Step 4: Cap retries, then escalate with the full history

Give 429s a retry budget (for example, 5 attempts with backoff). If the budget runs out, escalate - but with the attempt history attached so the human sees it was persistent, not a single blip.

Expected: humans get involved only for genuinely persistent problems, with full context.

### Step 5: Prove the classification in staging

Force a 429 from a test endpoint and watch the agent handle it end to end.

Expected: the agent backs off, retries, succeeds, and no escalation fires.

## When this applies

- Rate-limited calls trigger human escalation or abort the run
- The agent treats every non-200 as a fatal auth failure
- On-call gets paged for problems that resolve themselves in a minute

## When it doesn't

- The failure is a genuine 401 or 403 (those do need credential attention)
- The API returns 429 permanently (then it is a quota problem, talk to the vendor)
- No retry logic exists at all (build the classification table first)

## Compatibility

Okta, Entra ID, Slack, GitHub, and Stripe APIs; any API integration where the agent handles errors.

## Variant phrasings

### agent paged on-call for a rate limit

Same fix. The pager should never fire for something a sleep timer fixes.

### 429 treated as auth failure in agent error handling

Audit the error handler for a single catch-all branch. That branch is the bug; replace it with the table from Step 1.

## Why it happens

Error handling gets written once, early, as "if not 200, escalate." That is simple, it passes code review, and it is wrong for every retryable error. The agent has no concept of error classes because nobody gave it one. So the first 429 in production pages a human at 2 AM for a problem that needed 30 seconds of patience.

## Edge cases

- 429 without a retry-after header: use exponential backoff with jitter
- Mixed 429 and 401 in one run: handle each per the table, independently
- Provider-specific 429 shapes (some use 403 for rate limits): classify on the documented behavior, not just the number

## If it still fails

- Capture the status code, headers, and the classification decision before changing anything else.
- Reproduce with a single forced 429 so you are not debugging a crowd.
- Check the provider status page; platform incidents look exactly like classification bugs.

## Prevention

- The classification table is reviewed whenever a new API integration is added.
- Integration tests force each error class and assert the handling path.
- Alert on escalation volume; a spike means a classification bug or a real outage.

## Provenance

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