Errors and exit codes

Every dci command reports failures the same way: a single error message on stderr — with a hint when one is available — and a typed exit code that scripts and agents can branch on. You never need to handle raw HTTP responses.

Exit codes

Exit code	Error code	When
0	(success)	The command completed successfully.
1	CLI_ERROR / API_ERROR	A failure not covered by a more specific class below.
2	USAGE_ERROR	Invalid usage: unknown command or flag, or missing/malformed arguments.
10	AUTHENTICATION_FAILED	Not signed in, or the API token is malformed, expired, or revoked (HTTP 401).
11	PERMISSION_DENIED	The DoiT user or the active customer context lacks access (HTTP 403).
20	RESOURCE_NOT_FOUND	The requested resource does not exist (HTTP 404).
21	RESOURCE_CONFLICT	The operation conflicts with the resource's current state (HTTP 409).
30	VALIDATION_ERROR	The API rejected the arguments or payload (HTTP 400 or 422).
40	API_SERVER_ERROR	The API failed to process the request (HTTP 5xx). Retryable.
41	NETWORK_ERROR	The API was unreachable: DNS, connection, or timeout failure. Retryable.
50	RATE_LIMITED	Too many requests (HTTP 429). Retry after the server-provided delay.

Retryable failures (API_SERVER_ERROR, NETWORK_ERROR, RATE_LIMITED) are safe to retry; rate-limited responses include the delay the server asked for.

Agent mode

In agent mode, errors are written to stderr as a JSON envelope instead of free text:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Alert not found",
    "hint": "Check the identifier argument",
    "retryable": false,
    "http_status": 404,
    "request_id": "7f2e0c9b1a"
  }
}

Retryable failures also carry the server-provided delay when there is one:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "hint": "Retry after the server-provided delay",
    "retryable": true,
    "http_status": 429,
    "request_id": "a1b2c3d4e5",
    "retry_after": "2s"
  }
}

Field	Type	Description
code	string	Stable error class, matching the table above.
message	string	Human-readable description of what failed.
hint	string	Suggested next step, when one is available.
retryable	boolean	Whether retrying the same command may succeed.
http_status	integer	Underlying HTTP status, when the failure came from the API.
request_id	string	Request correlation ID to include in support tickets.
retry_after	string	Server-provided delay before retrying, for rate-limited requests.