# Errors and retries

## Tool-level results

A tool can succeed with **notes** (a part timed out, a board is stale) or fail with an `error` string. Read `notes` before trusting a composite answer.

| Message contains | What happened | What to do |
|---|---|---|
| `did not answer in time … call the same tool again in 30-60 s` | Upstream timed out for this account | Retry after a minute; the server keeps loading it in the background |
| `[STALE 120s]` in `credits.endpoints` | Upstream failed; you got the last good copy | Fine for most uses; retry for fresh data |
| `No credits on this account` | Balance is zero | Buy a pack; the next call works immediately |
| `404 not found` | Unknown handle, token or trade id | Check the identifier; for tokens outside the directory pass `chain` |
| `resting for Ns to stay clear of the failure rate-limit` | The upstream is degraded; we are protecting the connection | Wait the stated time; cached and stale data still serve |

## REST HTTP codes

See the table in [REST API](/rest). Retry only 502 and 429; never 400, 401 or 402.

## Idempotency

All tools are read-only; retrying is always safe. Cached repeats are billed at the documented price, retries after errors are free.