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-flashwith a DeepSeek key, not a Claude name). - Crypto sent before the order — it does not count; create the order first (payment).
serving: falseright afterrunning— 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.