Skip to content

Error reference

Auto-generated from crates/backend/src/error.rs and crates/cli/src/main.rs. Do not edit by hand — run scripts/docs/regen.py after changing the source.

HTTP error responses

Every backend handler returns errors through the ApiError enum, which serialises to a JSON body with two fields:

{ "error": "<error_type>", "message": "<human-readable message>" }

The error field is stable and safe for programmatic dispatch (alerting rules, retry logic). The message field is human-readable and may change between versions.

HTTP error field Variant When it fires
404 not_found ApiError::Database(sqlx::Error::RowNotFound) A sqlx::query_as! returns RowNotFound for a resource the handler expected to exist.
404 not_found ApiError::NotFound Explicitly returned by a handler when a path parameter (e.g. app_id, component_id) does not match an existing row, or via the OptionExt::ok_or_not_found() shorthand.
403 forbidden ApiError::Forbidden Effective permission check (core::permissions::effective_permission) returns less than the required level for the action, or workspace site access (can_access_site) denies the user.
401 unauthorized ApiError::Unauthorized No valid JWT, expired JWT, or no Authorization: Bearer <key> API key header on a route that requires one. The auth middleware short-circuits before the handler runs.
409 conflict ApiError::Conflict(msg) Business-logic conflict detected by the handler — for example, deleting a component that still has dependencies, or starting an application that is already in STARTING.
400 validation_error ApiError::Validation(msg) Request body failed validate_length / validate_optional_length, or a handler-specific check (date range invalid, slug malformed, enum value not in allowed set).
503 service_unavailable ApiError::ServiceUnavailable A dependency required to satisfy the request is down — typically the gateway is unreachable when the handler tries to dispatch a command to an agent.

Retry guidance

error field Safe to retry? Recommended back-off
unauthorized No — refresh the token first n/a
forbidden No — escalate to an operator n/a
not_found No n/a
validation_error No — fix the request n/a
conflict Depends on the body — usually no n/a
database_error Yes, with jitter exponential, 1s → 30s, cap at 5 retries
service_unavailable Yes exponential, 5s → 60s, cap at 10 retries
internal_error Sparingly linear, 30s, cap at 3 retries

CLI exit codes

The appctl CLI returns the following exit codes — schedulers can dispatch on these without parsing stdout. The mapping below is read from crates/cli/src/main.rs.

Code Constant Meaning
0 EXIT_SUCCESS The action completed (and, when --wait was passed, the target state was reached).
1 EXIT_FAILURE The action failed for a reason that is not covered by a more specific code.
2 EXIT_TIMEOUT --wait was passed and the timeout elapsed before the target state was reached.
3 EXIT_AUTH_ERROR Authentication failed — missing or invalid --api-key / APPCONTROL_API_KEY.
4 EXIT_NOT_FOUND The application (or component) named on the command line does not exist.
5 EXIT_PERMISSION_DENIED The API key is valid but lacks the required permission level on the target application.

Scheduler integration example

appctl start core-banking --wait --timeout 600
case $? in
  0) echo "Started; downstream jobs may run.";;
  2) echo "Timed out; trigger on-call."; exit 1;;
  3|5) echo "Auth or permission issue; rotate the API key."; exit 1;;
  *) echo "Failed; check the action_log for the trigger."; exit 1;;
esac