Errors and exit codes
Every refusal, what it means and what to do. Nothing is charged for any of them.
Exit codes
The CLI ends every command with one of these:
| Exit | Meaning | What to do |
|---|---|---|
| 0 | Done | |
| 1 | Failed | Read the message. The provider may have failed; nothing was charged. |
| 2 | Usage | Fix the command. A parameter in the wrong part says where it goes. |
| 3 | Needs confirmation | Show the user the preview and price. Only if they agree, run the command it prints (with --confirm). |
| 4 | Refused by a rule | Tell the user which rule. If they want it, supe approve <tool> --reason "…". |
| 5 | Wallet empty | Give the user the link to add credits. |
| 6 | Long job still running | supe job <job_id> later |
| 7 | Not signed in | supe login --email … |
Never retry a refused call with a different tool to get around a rule.
HTTP errors
Every error is {"error": {"code", "message", "details"}}:
{"error": {"code": "price_above_max", "message": "openalex#works_search costs 1 credit, above max_price 0 credits."}}| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request, invalid_input | Fix the call. invalid_input says which parameter and where it goes. |
| 401 | unauthorized | Missing or unknown key |
| 402 | insufficient_balance | The wallet can't cover it |
| 402 | limit_reached | A budget is used up |
| 402 | run_budget_exceeded | This run's budget is used up |
| 402 | price_above_max | The tool costs more than max_price |
| 403 | tool_disabled, tool_not_allowed | The tool is off, or this agent may not use it |
| 403 | workspace_frozen | All spending is paused |
| 403 | tool_not_compliant | The tool can't be used from this workspace |
| 404 | not_found | No such tool, tag, provider, run or job |
| 409 | needs_confirmation | Show details.will_do and details.price; resend with confirmation if they agree |
| 409 | confirmation_changed, confirmation_invalid | The input changed or the confirmation is stale. Ask again. |
| 409 | awaiting_signature | Waiting for the user's passkey. Send again. |
| 409 | idempotency_in_progress | The first request with this key is still running |
| 422 | idempotency_mismatch | Same Idempotency-Key, different body |
| 502 | provider_error, fetch_failed | The provider failed, or a file link couldn't be reached |
| 503 | tool_unavailable | The tool isn't available right now |
| 504 | provider_timeout, job_expired | The provider took too long, or a job's result expired |
The CLI maps these to exit codes: the 402 and 403 refusals are exit 4 (exit 5 for insufficient_balance), needs_confirmation is exit 3, and unauthorized is exit 7.