Skip to Content
supedocs

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:

ExitMeaningWhat to do
0Done
1FailedRead the message. The provider may have failed; nothing was charged.
2UsageFix the command. A parameter in the wrong part says where it goes.
3Needs confirmationShow the user the preview and price. Only if they agree, run the command it prints (with --confirm).
4Refused by a ruleTell the user which rule. If they want it, supe approve <tool> --reason "…".
5Wallet emptyGive the user the link to add credits.
6Long job still runningsupe job <job_id> later
7Not signed insupe 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."}}
StatusCodeMeaning
400invalid_request, invalid_inputFix the call. invalid_input says which parameter and where it goes.
401unauthorizedMissing or unknown key
402insufficient_balanceThe wallet can't cover it
402limit_reachedA budget is used up
402run_budget_exceededThis run's budget is used up
402price_above_maxThe tool costs more than max_price
403tool_disabled, tool_not_allowedThe tool is off, or this agent may not use it
403workspace_frozenAll spending is paused
403tool_not_compliantThe tool can't be used from this workspace
404not_foundNo such tool, tag, provider, run or job
409needs_confirmationShow details.will_do and details.price; resend with confirmation if they agree
409confirmation_changed, confirmation_invalidThe input changed or the confirmation is stale. Ask again.
409awaiting_signatureWaiting for the user's passkey. Send again.
409idempotency_in_progressThe first request with this key is still running
422idempotency_mismatchSame Idempotency-Key, different body
502provider_error, fetch_failedThe provider failed, or a file link couldn't be reached
503tool_unavailableThe tool isn't available right now
504provider_timeout, job_expiredThe 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.

On this page