## TL;DR

The dbt Cloud API token expired mid-run and calls started returning 401. The agent should detect the 401, refresh the credential through the account's token process, verify with a cheap API call, and resume from the last saved checkpoint instead of restarting.

## Error

```text
auth token expired mid-dbt-cloud run for the test-fix agent: auth error
```

## Steps

1. Detect the expiry: API calls returning 401 after succeeding earlier means the token lapsed. Expected: the agent classifies it as expiry, not a permissions change.
2. Stop making API calls; unauthenticated retries never succeed. Expected: no wasted requests.
3. Refresh the credential following the team's process (rotate the token in account settings or re-run the login flow the agent was given). Expected: a fresh, valid credential.
4. Verify with a cheap call (for example listing jobs with a small page). Expected: 200s again before resuming real work.
5. Resume from the last checkpoint (saved cursors, completed pages). Expected: the run continues where it stopped.

## When to use

- dbt Cloud API calls flip from 200 to 401 mid-run.
- Any long API session with expiring credentials.

## When not to use

- 401 from the very first call (the credential was never valid; fix it before starting).
- 403 responses (the credential works but lacks permission; a different problem).

## Tool compatibility

- dbt Cloud API; credential refresh is account-specific.

## Variant phrasings

### Token expires on a schedule the agent did not know

Learn the lifetime and refresh proactively before it lapses.

### Refresh succeeds but the run restarts from scratch

Checkpointing is the missing piece; persist progress continuously.

## Why it happens

API tokens have lifetimes. Long agent runs outlive short-lived tokens, and the first call after expiry fails. Without refresh-and-resume logic, the agent either loops on 401s or loses all progress.

## Edge cases

- Never log or persist the raw token value; store it in the credential manager the team uses.
- Some expiries are actually revocations (admin action); if refresh fails, escalate.
- Proactive refresh at 80 percent of token lifetime avoids the mid-run failure entirely.

## Provenance

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