Exit codes

Every cademi command ends with an exit code that tells scripts what happened without parsing the output. API errors map to a code by HTTP status, after the CLI's automatic retries.

Codes

The CLI retries network errors and 429, 500, 502, 503, and 504 responses before giving up (Commands), so codes 7 and 8 usually mean that the retries were exhausted. A 429 exits with 7 right away when the API asks for a wait longer than 60 seconds or the error is too_many_streams, and other 5xx statuses exit with 8 without a retry. A 503 that carries an API error code but no Retry-After header, such as storage_unavailable, also exits with 8 at the first response. CADEMI_MAX_RETRIES and CADEMI_MAX_RETRY_WAIT change the number of retries and the 60-second limit (Environment variables). With CADEMI_MAX_RETRIES=0, the CLI does not retry: the first error ends the command. What each status means for your integration is described in Errors.

cademi content products get prd_12 --json > product.json
case $? in
  0) echo "found" ;;
  5) echo "not found or outside the scope of the current credentials" ;;
  3|4) echo "check the credential with: cademi auth status" ;;
  *) echo "failed" ;;
esac

Error output

Errors always go to standard error. By default, an API error prints the error code and message, each item of details, a hint for common codes, the wait time for rate_limit_exceeded, and the request_id. Each item of details shows its field and message, followed in parentheses by its code and its reason when the API returns them, for example (reason: first_import_requires_release).

With --json, -o json, or --jq on the command, errors print as JSON instead:

• An API error prints the API's error envelope as the API returned it, with code, message, request_id, and details. See Errors.
• An error raised by the CLI itself uses the same shape on a single line, with the code cli_error. This includes errors in flags and arguments:

{"error":{"code":"cli_error","message":"no profile configured: run `cademi auth login` or set CADEMI_API_KEY"}}

• When a write fails after the CLI sent it, the error also has a request object with the method, the path, and the idempotency_key the CLI used. Pass that key with --idempotency-key to repeat the same write safely (Writes, retries, and idempotency). The error object and the exit code are the same as without it:

{"error":{"code":"internal_error","message":"...","request_id":"..."},"request":{"method":"POST","path":"/api/v3/users","idempotency_key":"0192f3a1-7c2e-7b4d-9e8f-3a5b6c7d8e9f"}}

• A cancellation prints nothing and exits with 130, unless it interrupted a write that was already sent: then the error carries the request object.

Warnings and progress can also go to standard error, so the whole stream is not always a single JSON document.

Branch on error.code, never on the message, which follows the language of CADEMI_LANG or your system locale.