Error reference¶
Auto-generated from
crates/backend/src/error.rsandcrates/cli/src/main.rs. Do not edit by hand — runscripts/docs/regen.pyafter changing the source.
HTTP error responses¶
Every backend handler returns errors through the ApiError enum, which serialises to a JSON body with two fields:
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. |