# Errors and traps

Errors are JSON: `{ "error": "CODE", "message": "why" }` with an HTTP status.

| status / code | when | what to do |
|---|---|---|
| 401 `UNAUTHORIZED` | no bearer, expired session, revoked key | re-authenticate; keys do not expire, sessions do after 30 days |
| 403 `FORBIDDEN` | a key managing keys; someone else's agent | use the person's session for key management |
| 404 `NOT_FOUND` | agent id not yours or deleted | check `GET /api/agents` |
| 400 `BAD_REQUEST` | validation: unknown tier, engine below its `minTier`, free-pod cap, domain under agentspodium.com | read `message`; it says which field |
| 409 `CONFLICT` | domain already in use | pick another |
| 429 | auth request rate limit | wait |

Traps that cost people time:

- **Pod answers but says nothing** — no model key. `PATCH /api/agents/:id/llm-key`.
- **Model name rejected by the provider** — the model must belong to the provider of the key (`deepseek-v4-flash` with a DeepSeek key, not a Claude name).
- **Crypto sent before the order** — it does not count; create the order first ([payment](payment.md)).
- **`serving: false` right after `running`** — booting; wait up to three minutes before acting.
- **A2A card returns a web page** — A2A toolset is off.
- **Domain refused** — names under agentspodium.com are assigned automatically; use a domain you own.