> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsfleet.net/llms.txt
> Use this file to discover all available pages before exploring further.
# Error codes
> API error response fields and stable error codes.
# Error codes
## Synopsis
Every API error uses a JSON Problem Details response. Each response carries a stable error code and documentation URL.
Use the error code for program logic. Use the request identifier when you contact support.
## Example with output
```json theme={"theme":"vesper"}
{
"docs_uri": "https://docs.agentsfleet.net/api-reference/error-codes#UZ-AGT-009",
"title": "Fleet not found",
"detail": "No fleet with id '0198a7ba-2c1d-7f08-8a45-3e9b6d2f1c70' in this workspace.",
"error_code": "UZ-AGT-009",
"request_id": "0198a7b5-3c8d-7e41-9a2b-6f1d4c7e8a05",
"user_message": "We couldn't find that Fleet. Check the workspace and fleet identifier."
}
```
## Options
The error format has no client option. Every response contains the first five fields below.
A conflict response also contains `current_state`. Some errors contain `user_message`.
| Field | Effect | Default | Unit or range |
| --------------- | ---------------------------------------- | -------- | ----------------------------------- |
| `docs_uri` | Links to this error. | Included | URL |
| `title` | Gives a stable short label. | Included | Text |
| `detail` | Explains this failure. | Included | Text that varies by request |
| `error_code` | Identifies the failure for client logic. | Included | Registered code below |
| `request_id` | Identifies the request for support. | Included | Server-generated value |
| `current_state` | Names the state that blocked a change. | Omitted | Included on HTTP 409 responses |
| `user_message` | Gives text safe to show to a user. | Omitted | Included when the error defines one |
## Errors
### Identifiers
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------------ | ---- | ------------------------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `UZ-UUIDV7-009` | 400 | Invalid identifier shape | The supplied identifier does not match the expected version 7 universally unique identifier shape. | Use identifiers returned by agentsfleet. |
### Service failures
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------------------- | ---- | ------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `UZ-INTERNAL-001` | 503 | Service unavailable | A required service is unavailable. Try again shortly. | Clients cannot prevent this failure. Keep retry handling ready. |
| `UZ-INTERNAL-002` | 500 | Request failed | We couldn't finish that request. Try again shortly. | Clients cannot prevent this failure. Keep retry handling ready. |
| `UZ-INTERNAL-003` | 500 | Request failed | The request could not finish. Retry it, then report the error code and request identifier if it continues. | Clients cannot prevent this failure. Keep retry handling ready. |
### Request
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------ | ---- | ----------------- | ----------------------------------------------------------------------------- | --------------------------------------------------- |
| `UZ-REQ-001` | 400 | Invalid request | That request wasn't valid. Double-check the values you entered and try again. | Validate request fields before sending the request. |
| `UZ-REQ-002` | 413 | Payload too large | Request body exceeds the maximum allowed size. | Validate request fields before sending the request. |
### Workspaces
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------------------ | ---- | ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `UZ-WORKSPACE-001` | 409 | Workspace name already exists | A workspace with that name already exists. Check the refreshed list or choose another name. | Use a unique workspace name within the current tenant. |
### Authentication
| Code | HTTP | Title | Why and fix | Prevent |
| -------------------------------------- | ---- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `UZ-AUTH-001` | 403 | Forbidden | You need operator access for that. Ask a tenant operator or admin to manage API keys. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-002` | 401 | Unauthorized | Authentication required. Provide a valid Bearer token. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-003` | 401 | Token expired | Your authentication token has expired. Re-authenticate. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-004` | 503 | Authentication service unavailable | Authentication service is temporarily unavailable. Retry shortly. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-005` | 404 | Session not found | Session was not found. It may have expired or been invalidated. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-006` | 401 | Session expired | Your session has expired. Please sign in again. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-011` | 400 | Verification code did not match | The 6-digit verification code did not match what the dashboard issued. Double-check the code shown in your browser and try again. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-012` | 410 | Login session already consumed | This login session has already been consumed. Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-013` | 410 | Login session aborted | This login session was aborted (too many wrong codes, explicit cancel, or replaced by a newer session). Start over with `agentsfleet login`. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-014` | 409 | Login session not approved | This login session has not been approved in the dashboard yet. Approve it in your browser before submitting a verification code. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-015` | 409 | Login session already approved | This login session has already been approved. Do not call /approve a second time. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-016` | 400 | Invalid command-line public key | The supplied public\_key is malformed. Expect base64url-encoded P-256 SubjectPublicKeyInfo. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-017` | 400 | Invalid token name | token\_name must contain 1 to 64 characters from space through tilde. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-018` | 400 | Invalid verification code shape | verification\_code must contain exactly 6 decimal digits. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-019` | 400 | Invalid ciphertext | ciphertext is missing or empty. Expect a base64url-encoded AES-256-GCM output. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-020` | 400 | Invalid nonce | nonce is missing, empty, or the wrong length. Expect a base64url-encoded 12-byte value. | Keep sign-in sessions and credentials current. |
| `UZ-AUTH-022` | 403 | Insufficient scope | You need an additional scope for that. Ask an agentsfleet admin to grant the scope this action requires. | Keep sign-in sessions and credentials current. |
### API
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------ | ---- | -------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `UZ-API-001` | 429 | Too many requests | The API is handling its maximum number of requests. Wait for the Retry-After delay, then retry. | Limit concurrent requests and honor retry delays. |
| `UZ-API-002` | 503 | Activity stream capacity reached | The API is serving its maximum number of activity streams. Close unused dashboard tabs or retry shortly. | Limit concurrent requests and honor retry delays. |
### Fleet keys
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------------------- | ---- | ------------------- | ----------------------------------------------- | --------------------------------------------------- |
| `UZ-FLEETKEY-001` | 404 | Fleet key not found | Fleet key not found. Verify the fleet\_key\_id. | Use a current Fleet API key for the intended fleet. |
### Webhooks
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------- | ---- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `UZ-WH-001` | 404 | Fleet not found for webhook | No fleet is registered for this webhook endpoint. | Keep webhook signing secrets matched and service clocks synchronized. |
| `UZ-WH-002` | 400 | Malformed webhook | Webhook payload could not be parsed. Check Content-Type and body. | Keep webhook signing secrets matched and service clocks synchronized. |
| `UZ-WH-010` | 401 | Invalid webhook signature | Webhook signature verification failed. Confirm the signing secret stored for this provider (Slack/Clerk/other) matches the one configured upstream. | Keep webhook signing secrets matched and service clocks synchronized. |
| `UZ-WH-011` | 401 | Stale webhook timestamp | Webhook request timestamp is outside the allowed 5-minute drift window. This may indicate a replay attack or clock skew. | Keep webhook signing secrets matched and service clocks synchronized. |
| `UZ-WH-020` | 401 | Webhook credential not configured | Create a random webhook secret with at least 32 bytes. Store it as this source's webhook\_secret, configure the same value upstream, then resend. | Keep webhook signing secrets matched and service clocks synchronized. |
| `UZ-WH-021` | 404 | Connector installation is not mapped | Reconnect the provider App to the intended workspace before redelivering the event. | Keep webhook signing secrets matched and service clocks synchronized. |
| `UZ-WH-022` | 404 | No fleet subscription matched | Bind the repository and event to an active fleet with an approved integration grant. | Keep webhook signing secrets matched and service clocks synchronized. |
| `UZ-WH-030` | 413 | Webhook payload too large | Webhook body exceeds the 1 MiB ingest limit. Reduce the payload size or filter at the source. | Keep webhook signing secrets matched and service clocks synchronized. |
### Slack
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------ | ---- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `UZ-SLK-010` | 401 | Invalid Slack signature | The Slack request signature did not verify. Confirm the platform Slack app signing secret matches the one vaulted at slack-app/signing\_secret. | Keep Slack app credentials, permissions, and clocks current. |
| `UZ-SLK-011` | 401 | Stale Slack timestamp | The Slack request timestamp is outside the allowed 5-minute drift window — a replay attempt or a skewed server clock. | Keep Slack app credentials, permissions, and clocks current. |
| `UZ-SLK-020` | 200 | Slack team not installed | The Slack team that sent this event has no connector install, so the event is acknowledged (200) and ignored. Re-run Connect Slack in the dashboard to (re)install. | Keep Slack app credentials, permissions, and clocks current. |
| `UZ-SLK-022` | 502 | Slack token exchange failed | The Slack OAuth code could not be exchanged for a bot token. Retry the connect flow; if the error continues, verify the platform Slack app credentials. | Keep Slack app credentials, permissions, and clocks current. |
| `UZ-SLK-030` | 502 | Slack answer post failed | The channel bot's answer could not be delivered to Slack (missing chat:write, a 429, or a Slack outage). It is logged and retried with backoff; the run itself never fails. | Keep Slack app credentials, permissions, and clocks current. |
### Tools
| Code | HTTP | Title | Why and fix | Prevent |
| -------------------------------------- | ---- | ------------ | --------------------------------------------------------------- | ------------------------------------- |
| `UZ-TOOL-005` | 400 | Unknown tool | Unknown tool name. Check spelling against the known tools list. | Declare every tool used by the fleet. |
### Fleets
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------ | ---- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `UZ-AGT-003` | 424 | Fleet credential missing | A required credential is not in the vault. Add it with: `agentsfleet secret create ` | Use fleet identifiers from the current workspace. |
| `UZ-AGT-004` | 500 | Fleet unavailable | The fleet could not accept work. Check that the fleet exists and is active, then retry. | Use fleet identifiers from the current workspace. |
| `UZ-AGT-006` | 409 | Fleet name already exists | A Fleet with this name already exists. Use `agentsfleet kill ` first, then deploy again. | Use fleet identifiers from the current workspace. |
| `UZ-AGT-008` | 400 | Invalid fleet config | That fleet's config isn't valid. Check the trigger, tools, credentials, and budget fields, then try again. | Use fleet identifiers from the current workspace. |
| `UZ-AGT-009` | 404 | Fleet not found | We couldn't find that Fleet. It may have been deleted, or the identifier doesn't match one in this workspace. | Use fleet identifiers from the current workspace. |
| `UZ-AGT-010` | 409 | Fleet state transition not allowed | That action isn't available for this Fleet right now — check its current status and try again. | Use fleet identifiers from the current workspace. |
| `UZ-AGT-011` | 400 | Fleet files disagree on `name:` | This Fleet Bundle's files disagree on its name. `SKILL.md` and `TRIGGER.md` must match. Fix the source and try again. | Use fleet identifiers from the current workspace. |
| `UZ-AGT-012` | 409 | Fleet is paused | This Fleet is paused. Resume it before sending new work. | Use fleet identifiers from the current workspace. |
| `UZ-AGT-013` | 500 | Fleet install rolled back | We couldn't finish setting up your fleet. Nothing was created — try again. | Use fleet identifiers from the current workspace. |
| `UZ-AGT-014` | 412 | Fleet source is stale | Someone else edited this Fleet's source since you opened it. Reload to see their change, then re-apply your edit. | Use fleet identifiers from the current workspace. |
### Schedules
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------------- | ---- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `UZ-SCHED-001` | 422 | Invalid schedule | cron must be a valid five-field expression and timezone must name a supported region. | Use a valid schedule, cron expression, timezone, and configured QStash ingress. |
| `UZ-SCHED-002` | 404 | Schedule not found | No schedule matches this identifier for the selected Fleet. | Use a valid schedule, cron expression, timezone, and configured QStash ingress. |
| `UZ-SCHED-003` | 409 | Schedule limit reached | A Fleet can hold at most 32 schedules. Remove one before creating another. | Use a valid schedule, cron expression, timezone, and configured QStash ingress. |
| `UZ-SCHED-004` | 502 | Schedule provider unavailable | QStash did not confirm the change. Run the schedule sync command shown by the client. | Use a valid schedule, cron expression, timezone, and configured QStash ingress. |
| `UZ-SCHED-005` | 401 | Invalid schedule signature | QStash delivery signature verification failed. Confirm the vaulted signing keys and ingress URL. | Use a valid schedule, cron expression, timezone, and configured QStash ingress. |
| `UZ-SCHED-006` | 409 | Schedule update busy | Another schedule mutation holds the synchronization lease. Retry after the reported delay. | Use a valid schedule, cron expression, timezone, and configured QStash ingress. |
| `UZ-SCHED-007` | 503 | Schedule service unavailable | QStash credentials are not configured. Follow the registration playbook and roll agentsfleetd. | Use a valid schedule, cron expression, timezone, and configured QStash ingress. |
| `UZ-SCHED-008` | 409 | Schedule source already exists | A schedule already uses this source key for the selected Fleet. Pick a different source or update the existing schedule. | Use a valid schedule, cron expression, timezone, and configured QStash ingress. |
### Fleet Bundles
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------------ | ---- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `UZ-BUNDLE-001` | 400 | Invalid Fleet Bundle | That Fleet Bundle isn't valid. It's missing `SKILL.md`, or has an unsafe or oversized file. Check the source and try again. | Check Fleet Bundle files and limits before upload. |
| `UZ-BUNDLE-002` | 404 | Fleet Bundle not found | We couldn't find that Fleet Bundle. It may not be installed in this workspace yet — check the Fleet library. | Check Fleet Bundle files and limits before upload. |
| `UZ-BUNDLE-003` | 424 | Fleet Bundle secrets missing | This Fleet Bundle needs secrets this workspace doesn't have yet. Add the missing secrets, then install again. | Check Fleet Bundle files and limits before upload. |
| `UZ-BUNDLE-004` | 502 | Fleet Bundle fetch failed | We couldn't fetch that Fleet Bundle from GitHub. Check the source and try again. | Check Fleet Bundle files and limits before upload. |
| `UZ-BUNDLE-005` | 503 | Fleet Bundle storage unavailable | We couldn't store your Fleet Bundle right now. Try again shortly. | Check Fleet Bundle files and limits before upload. |
### Secrets
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------------- | ---- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| `UZ-VAULT-001` | 400 | Secret data must be a non-empty JSON object | That secret needs at least one field. Enter it as a JSON object with one or more keys — not a bare string or list. | Use a valid workspace secret name and value. |
| `UZ-VAULT-002` | 400 | Secret data too large | That secret is too large. Keep it under 4 KiB. Trim or shorten the fields. | Use a valid workspace secret name and value. |
| `UZ-VAULT-003` | 404 | Secret not found | We couldn't find that secret. It may have already been deleted — refresh the list. | Use a valid workspace secret name and value. |
| `UZ-VAULT-004` | 409 | Secret still referenced by model entries | This key is used by one or more models in your registry. Remove those entries first, then delete the key. | Use a valid workspace secret name and value. |
| `UZ-VAULT-005` | 409 | Secret name already taken | A secret with that name already exists. Rename this one, or open the existing secret and replace its value. | Use a valid workspace secret name and value. |
### Model providers
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------------------- | ---- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `UZ-PROVIDER-001` | 400 | secret\_ref required when mode=self\_managed | Pick a secret to activate. Choose a stored secret before switching to a self-managed model. | Configure a supported provider, model, and secret. |
| `UZ-PROVIDER-002` | 400 | Secret not found | We couldn't find that secret. Store it under Secrets & ENVs, then try again. | Configure a supported provider, model, and secret. |
| `UZ-PROVIDER-003` | 400 | Secret JSON missing required field | That secret is missing required fields. It needs a provider set (and an API key for a named provider) — edit it under Secrets & ENVs and add them. | Configure a supported provider, model, and secret. |
| `UZ-PROVIDER-004` | 400 | Model not in library | That model isn't in our library yet. Pick a listed model, or ask us to add support for it. | Configure a supported provider, model, and secret. |
| `UZ-PROVIDER-005` | 400 | Custom endpoint base\_url invalid or unsafe | That endpoint URL isn't allowed. Use a public https URL for your custom endpoint. | Configure a supported provider, model, and secret. |
| `UZ-PROVIDER-006` | 404 | Library model not found | We couldn't find that model in the library. Refresh the list and try again. | Configure a supported provider, model, and secret. |
| `UZ-PROVIDER-007` | 409 | Library model is the active platform default | This model is the active platform default — point the default at another model before deleting it. | Configure a supported provider, model, and secret. |
| `UZ-PROVIDER-008` | 409 | Library model already exists | That model is already in the library. Edit the existing entry instead of adding a duplicate. | Configure a supported provider, model, and secret. |
| `UZ-PROVIDER-009` | 500 | Platform model key not configured | Platform defaults aren't set up on this deployment yet. Keep your current provider for now, or contact support. | Configure a supported provider, model, and secret. |
| `UZ-PROVIDER-010` | 500 | Tenant has no primary workspace | Something's off with your account setup. Contact support with the request id below. | Configure a supported provider, model, and secret. |
### Tenant models
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------------ | ---- | ------------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------ |
| `UZ-MODELS-001` | 409 | Cannot delete the active model entry | This is your active model — switch to a different one first, then remove this entry. | Use a model available to the tenant. |
| `UZ-MODELS-002` | 404 | Referenced secret not found | We couldn't find that key. Store it under Secrets & ENVs first, or pick an existing key. | Use a model available to the tenant. |
| `UZ-MODELS-003` | 409 | Model entry already exists | You already have this model registered with that key. Edit the existing entry instead. | Use a model available to the tenant. |
| `UZ-MODELS-004` | 404 | Model entry not found | We couldn't find that model entry. It may have already been removed — refresh the list. | Use a model available to the tenant. |
### Dashboard preferences
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------------- | ---- | -------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------- |
| `UZ-PREFS-001` | 400 | Unknown preference key | That setting doesn't exist. Reload the page and try again. | Write only preference keys the dashboard declares, with small values. |
| `UZ-PREFS-002` | 400 | Preference value too large | That setting is too large to save. Reload the page and try again. | Write only preference keys the dashboard declares, with small values. |
### Fleet library catalog
| Code | HTTP | Title | Why and fix | Prevent |
| -------------------------------------------- | ---- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `UZ-CATALOG-001` | 404 | Fleet library entry not found | We couldn't find that fleet. It may have already been removed — refresh the page. | Fetch a bundle before publishing a fleet, and unpublish before deleting one. |
| `UZ-CATALOG-002` | 409 | Cannot publish a fleet with no bundle | There's no bundle for this fleet yet. Fetch it from its repository first, then publish. | Fetch a bundle before publishing a fleet, and unpublish before deleting one. |
| `UZ-CATALOG-003` | 409 | Cannot delete a published fleet | This fleet is published. Unpublish it first, then delete it. | Fetch a bundle before publishing a fleet, and unpublish before deleting one. |
| `UZ-CATALOG-004` | 409 | Catalog id already taken by another repository | A different repository already owns this fleet's name. Rename the bundle, or confirm you want to replace it. | Fetch a bundle before publishing a fleet, and unpublish before deleting one. |
| `UZ-CATALOG-005` | 412 | Catalog entry changed since you loaded it | Someone else edited this catalog entry since you opened it. Refresh to see their change, then re-apply your edit. | Fetch a bundle before publishing a fleet, and unpublish before deleting one. |
### Library listings
| Code | HTTP | Title | Why and fix | Prevent |
| -------------------------------------------- | ---- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UZ-LIBRARY-001` | 400 | Pagination cursor is malformed | That page link is no longer valid. Go back to the first page and try again. | Page with the `next_cursor` returned by the previous page, keep `limit` within 1 to 100, and start over from the first page after changing a filter. |
| `UZ-LIBRARY-002` | 400 | Pagination cursor does not match this request | The filters changed since that page was loaded. Start again from the first page. | Page with the `next_cursor` returned by the previous page, keep `limit` within 1 to 100, and start over from the first page after changing a filter. |
| `UZ-LIBRARY-003` | 400 | Pagination or filter input out of bounds | That request asked for too much at once. Try a smaller page size or a shorter filter. | Page with the `next_cursor` returned by the previous page, keep `limit` within 1 to 100, and start over from the first page after changing a filter. |
| `UZ-LIBRARY-004` | 503 | Catalogue version unavailable | The model catalogue is temporarily unavailable. Try again shortly. | Page with the `next_cursor` returned by the previous page, keep `limit` within 1 to 100, and start over from the first page after changing a filter. |
| `UZ-LIBRARY-005` | 500 | Response exceeded its size ceiling | We couldn't build that page. Try again shortly, and contact support with the request id if it continues. | Page with the `next_cursor` returned by the previous page, keep `limit` within 1 to 100, and start over from the first page after changing a filter. |
| `UZ-LIBRARY-006` | 503 | Data service temporarily unavailable | We couldn't reach the database. Try again shortly. | Page with the `next_cursor` returned by the previous page, keep `limit` within 1 to 100, and start over from the first page after changing a filter. |
| `UZ-LIBRARY-008` | 409 | Credential was deleted while it was being referenced | That key was deleted while you were saving. Refresh and pick another key. | Page with the `next_cursor` returned by the previous page, keep `limit` within 1 to 100, and start over from the first page after changing a filter. |
### Startup
| Code | HTTP | Title | Why and fix | Prevent |
| -------------------------------------------- | ---- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `UZ-STARTUP-001` | 500 | Required settings missing | The service cannot start because required settings are missing. An operator must add them before retrying startup. | Operators should verify required service settings before startup. |
| `UZ-STARTUP-002` | 500 | Settings could not load | The service cannot start because one or more settings are invalid. An operator must correct them before retrying startup. | Operators should verify required service settings before startup. |
| `UZ-STARTUP-003` | 500 | Data service unavailable | The service cannot start because a required data service is unreachable. An operator must restore access before retrying startup. | Operators should verify required service settings before startup. |
| `UZ-STARTUP-004` | 500 | Event service unavailable | The service cannot start because its event service is unreachable. An operator must restore access before retrying startup. | Operators should verify required service settings before startup. |
| `UZ-STARTUP-005` | 500 | Stored data is not ready | The service cannot start because stored data is not ready. An operator must finish the data update before retrying startup. | Operators should verify required service settings before startup. |
| `UZ-STARTUP-006` | 500 | Service could not start | The host lacked enough memory during startup. Free memory or use a larger host, then retry. | Operators should verify required service settings before startup. |
### Runners
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------ | ---- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `UZ-RUN-001` | 401 | Invalid runner token | The Bearer runner\_token is missing, malformed, or not recognized. Re-register the runner. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-005` | 409 | Stale fencing token | The lease was reclaimed by a newer holder. This report is rejected; the current holder's result wins. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-006` | 404 | Lease not found | No active lease matches this lease\_id for the presenting runner; it may have expired, been reclaimed, or never existed. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-009` | 401 | Runner admin state blocks access | This runner is cordoned, draining, drained, or revoked and cannot call the runner plane. Re-enroll the host to mint a fresh runner token. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-010` | 409 | Lease exceeded max runtime | The lease reached its maximum runtime and cannot renew. The runner stops the child and reports any result. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-011` | 409 | Lease lost | The lease moved to another runner before renewal. The former runner must stop its child. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-012` | 402 | Lease renewal blocked: no credits | The tenant balance cannot cover another run slice. The lease does not renew, and the run stops cleanly. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-013` | 400 | Renew body malformed | The renew request body could not be parsed. Token counts become zero, but the renewed slice still charges for runtime. The lease still renews. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-014` | 404 | Runner not found | We couldn't find that runner. It may have been removed — refresh the list. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-015` | 402 | Lease renewal blocked: fleet budget exhausted | The fleet reached its daily\_dollars or monthly\_dollars limit from `TRIGGER.md`. The lease cannot renew, so the run stops. This differs from UZ-RUN-012, which reports a low tenant balance. | Keep runner settings and lease health within configured limits. |
| `UZ-RUN-016` | 409 | Active runner must be revoked before deletion | This runner is still live. Revoke it first, then delete it. | Keep runner settings and lease health within configured limits. |
### Runs
| Code | HTTP | Title | Why and fix | Prevent |
| -------------------------------------- | ---- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `UZ-EXEC-003` | 500 | Run timed out | The run exceeded its time limit and stopped. | Check runner settings and access before starting work. |
| `UZ-EXEC-004` | 500 | Run memory limit reached | The run reached its memory limit and stopped. | Check runner settings and access before starting work. |
| `UZ-EXEC-005` | 500 | Run resource limit reached | The run reached a resource limit and stopped. | Check runner settings and access before starting work. |
| `UZ-EXEC-006` | 500 | Runner connection lost | The connection to the runner was lost. | Check runner settings and access before starting work. |
| `UZ-EXEC-007` | 500 | Run lease expired | The run took too long and its lease expired. | Check runner settings and access before starting work. |
| `UZ-EXEC-008` | 500 | Run stopped during renewal | The run stopped because its lease was lost, expired, or refused renewal. | Check runner settings and access before starting work. |
| `UZ-EXEC-009` | 500 | Runner security check failed | Check the runner security settings before retrying. | Check runner settings and access before starting work. |
| `UZ-EXEC-010` | 500 | Run crashed | The run process crashed. Check the activity stream for details. | Check runner settings and access before starting work. |
| `UZ-EXEC-011` | 403 | Landlock policy deny | Landlock policy denied the filesystem operation. | Check runner settings and access before starting work. |
| `UZ-EXEC-012` | 500 | Runner fleet init failed | Runner fleet initialization failed. Check configuration. | Check runner settings and access before starting work. |
| `UZ-EXEC-013` | 500 | Runner fleet run failed | The runner could not finish the fleet run. Check the activity stream. | Check runner settings and access before starting work. |
| `UZ-EXEC-014` | 400 | Run settings invalid | The run settings are invalid. Check the fleet files before retrying. | Check runner settings and access before starting work. |
| `UZ-EXEC-015` | 402 | Run stopped: fleet limit reached | The run stopped because the fleet reached its configured limit. | Check runner settings and access before starting work. |
| `UZ-EXEC-016` | 401 | Runner token rejected | The control plane rejected this host's agt\_r runner token (401/403) on the heartbeat. Retrying can't fix it — mint a fresh agt\_r and issue the host's runner token again, then restart the runner. | Check runner settings and access before starting work. |
### Approvals
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------------------- | ---- | ---------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `UZ-APPROVAL-001` | 400 | Approval parse failed | That approval gate's config is invalid. Check the gates section in TRIGGER.md. | Resolve only current approval requests. |
| `UZ-APPROVAL-002` | 404 | Approval not found | That approval action wasn't found. It may have already timed out or been resolved elsewhere. | Resolve only current approval requests. |
| `UZ-APPROVAL-003` | 401 | Approval invalid signature | That approval callback couldn't be verified. Check the signing secret configuration. | Resolve only current approval requests. |
| `UZ-APPROVAL-004` | 503 | Approval service unavailable | Approvals are temporarily unavailable. We deny requests while this service is down. Try again shortly. | Resolve only current approval requests. |
| `UZ-APPROVAL-005` | 400 | Approval condition invalid | That approval gate's condition is invalid. Check the gate's condition expression for a supported operator. | Resolve only current approval requests. |
| `UZ-APPROVAL-006` | 409 | Approval already resolved | Someone already resolved this. Refresh to see the outcome and who resolved it. | Resolve only current approval requests. |
### Memory
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------ | ---- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| `UZ-MEM-002` | 404 | Fleet not found for memory op | The fleet\_id does not exist or does not belong to the requesting workspace. Verify the fleet\_id and workspace scope. | Use an existing fleet and a valid memory category. |
| `UZ-MEM-003` | 503 | Saved memory unavailable | Saved memory is unavailable. The fleet uses temporary workspace memory until the service recovers. | Use an existing fleet and a valid memory category. |
| `UZ-MEM-004` | 404 | Memory entry not found | That memory entry is already gone — the fleet isn't holding anything under that key. | Use an existing fleet and a valid memory category. |
### API keys
| Code | HTTP | Title | Why and fix | Prevent |
| ------------------------------------------ | ---- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `UZ-APIKEY-001` | 401 | Invalid API key | API key is invalid or revoked. Mint a replacement with: `POST /v1/workspaces/{ws}/fleet-keys` | Use current API key identifiers and replace revoked keys. |
| `UZ-APIKEY-003` | 404 | API key not found | We couldn't find that API key. It may have already been deleted — refresh the list. | Use current API key identifiers and replace revoked keys. |
| `UZ-APIKEY-004` | 401 | API key has been revoked | This key was revoked and can no longer authenticate. Mint a replacement with: POST /v1/api-keys | Use current API key identifiers and replace revoked keys. |
| `UZ-APIKEY-005` | 409 | Key name already exists in this tenant | An API key with that name already exists. Pick a different name for this tenant. | Use current API key identifiers and replace revoked keys. |
| `UZ-APIKEY-006` | 409 | API key is already revoked | That API key is already revoked. Refresh the list to see its current state. | Use current API key identifiers and replace revoked keys. |
| `UZ-APIKEY-007` | 409 | active cannot be set to true; mint a new key instead | A revoked key can't be reactivated. Mint a new key instead. | Use current API key identifiers and replace revoked keys. |
| `UZ-APIKEY-008` | 409 | Active API key must be revoked before deletion | Revoke this key before deleting it. Revoke it first, then delete the revoked key. | Use current API key identifiers and replace revoked keys. |
### Integration grants
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------------- | ---- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `UZ-GRANT-001` | 403 | No integration grant for service | This fleet has no approved grant for the target service. Request one with: `POST /v1/workspaces/{ws}/fleets/{id}/integration-requests` | Use active integration grants approved for the fleet. |
| `UZ-GRANT-002` | 404 | Integration grant not found | We couldn't find that grant request. It may have already been resolved — refresh the list. | Use active integration grants approved for the fleet. |
| `UZ-GRANT-003` | 409 | Grant already resolved | Someone already resolved this. Refresh to see the outcome and who resolved it. | Use active integration grants approved for the fleet. |
### Credentials
| Code | HTTP | Title | Why and fix | Prevent |
| -------------------------------------- | ---- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `UZ-CRED-001` | 404 | Integration not connected | That integration isn't connected. Connect it from the Integrations page, then try again. | Create required workspace secrets before starting a run. |
| `UZ-CRED-002` | 503 | Credential broker not configured | The on-demand credential broker is not wired on this deployment (a boot-time misconfiguration, not a client error). An operator must configure it before runners can mint credentials. | Create required workspace secrets before starting a run. |
### GitHub
| Code | HTTP | Title | Why and fix | Prevent |
| ---------------------------------- | ---- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `UZ-GH-001` | 409 | GitHub App reconnect required | The GitHub App installation is gone (uninstalled or revoked), so no token can be minted. Reconnect GitHub from the dashboard — the fleet stays blocked until the App is reinstalled. | Keep the GitHub App installed with required repository access. |
| `UZ-GH-002` | 502 | GitHub token mint failed | GitHub did not return an installation token (upstream 5xx, network, or a malformed exchange response). This is temporary. Retry shortly; if the error continues, check GitHub status and the App configuration. | Keep the GitHub App installed with required repository access. |
### Connectors
| Code | HTTP | Title | Why and fix | Prevent |
| -------------------------------------- | ---- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `UZ-CONN-001` | 503 | Connector not configured | This connector isn't set up yet. Contact your operator to enable it. | Check the provider connection before sending requests. |
| `UZ-CONN-002` | 400 | Invalid connect state | That connection attempt expired or was already used. Start connecting again from the dashboard. | Check the provider connection before sending requests. |
| `UZ-CONN-003` | 502 | Connector vendor call exceeded its deadline | We couldn't reach that service right now. Try again shortly. | Check the provider connection before sending requests. |
| `UZ-CONN-004` | 404 | Unknown connector provider | We don't recognize that connector. Check the available connectors on the dashboard. | Check the provider connection before sending requests. |
| `UZ-CONN-006` | 502 | Connector OAuth exchange failed | That connection didn't go through. Try connecting again from the dashboard. | Check the provider connection before sending requests. |
| `UZ-CONN-007` | 500 | Connector catalog lookup failed | We couldn't load your connectors right now. Try refreshing — if it keeps failing, contact support. | Check the provider connection before sending requests. |
| `UZ-CONN-008` | 403 | Connector installation ownership not verified | We couldn't verify that this GitHub installation belongs to you. Sign in with the owning GitHub account and try again. | Check the provider connection before sending requests. |
## Related pages
* [API introduction](/api-reference/introduction)
* [API scopes](/api-reference/scopes)
* [Troubleshoot fleets](/fleets/troubleshooting)