Errors and exit codes

The CLI reports failures in a single, stable shape. The exit status says only whether the command succeeded; the detail is in a JSON error envelope on stderr.

Exit codes

The exit status carries only two meanings:

The exit status is deliberately binary. Scripts should branch on the code field of the error envelope, not on numeric exit codes.

The error envelope

{
  "error": {
    "code": "auth.missing",
    "message": "No API token found.",
    "next": "Run 'deel auth login', set DEEL_TOKEN, or pipe one with --token-stdin.",
    "request_id": "8b1c1a2e-3f96-4d05-a172-9e6b8c4d0f13"
  }
}

Fields of the error object:

The envelope is always written to stderr, so stdout stays empty on failure and pipelines do not receive partial output.

CLI error codes

These codes come from the CLI itself, distinct from codes the API returns:

API errors

When the API returns an error status after the retry policy is exhausted, the CLI maps the response into the same envelope:

• code is the API’s error code when the response includes one, otherwise http.<status>, for example http.403.
• For validation responses with an errors array, message lists each field and its problem, for example amount: must be a positive number; date_submitted: is required.
• request_id is always present so that Deel support can locate the request.

{
  "error": {
    "code": "http.403",
    "message": "Request failed with status 403",
    "request_id": "8b1c1a2e-3f96-4d05-a172-9e6b8c4d0f13"
  }
}

The Hypertext Transfer Protocol (HTTP) status codes and their meanings are documented in the API reference.

Handle errors in scripts

Capture stderr and read code with jq:

if ! OUT=$(deel adjustments create --invoice --input file://bonus.json 2>err.json); then
  CODE=$(jq -r '.error.code' err.json)
  case "$CODE" in
    auth.*)   echo "authentication problem: $(jq -r '.error.next' err.json)" ;;
    input.*)  echo "fix the request body: $(jq -r '.error.message' err.json)" ;;
    http.429) echo "rate limited after retries; try again later" ;;
    *)        echo "failed with $CODE (request $(jq -r '.error.request_id' err.json))" ;;
  esac
  exit 1
fi

Next steps