error, code and error_type. For the REST surface see
Scenario Methods → Errors.
| Symptom | error_type / shape | Cause | Resolution |
|---|---|---|---|
401 | unauthorized | Missing, revoked or misconfigured master key | Re-create the ak_... key on the console’s API Keys page and re-run setup — see Authentication |
402 | insufficient_credits with action (upgrade or topup_or_upgrade) and a console URL | Monthly allowance and extra credits used up | Top up or upgrade in the console — see Subscription & Billing. No upstream call was made |
| Unknown tool, with suggestions | fuzzy-match suggestions in the result | Typo or guessed name | Use a suggestion, or re-run find_tools. Don’t retry blindly |
| Missing / invalid params | 400 from the provider or a validation message | Skipped the describe step | Always describe_tool first and copy execute_as |
| Rate limited | 429 / rate_limit | The provider throttled the call | Wait, then retry |
| Provider failed | 5xx, timeout, or an error inside the provider’s payload | Upstream outage or a broken endpoint | Retry via a sibling surface or version, or another provider — see Provider Failover. Cap at two or three attempts; each is billed |
disabled: true in a 200 result | { "disabled": true, "category": "social", "message": "…", "reenable_at": "…" } | You switched the category off in the console | Don’t retry and don’t route around it; re-enable under Marketplace if needed |
When in doubt, run the free
agentkey_account tool:
it confirms both your balance and every provider’s health.