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

{
  "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 <NAME>`	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 <name>` 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.

​Error codes

​Synopsis

​Example with output

​Options

​Errors

​Identifiers

​Service failures

​Request

​Workspaces

​Authentication

​API

​Fleet keys

​Webhooks

​Slack

​Tools

​Fleets

​Schedules

​Fleet Bundles

​Secrets

​Model providers

​Tenant models

​Dashboard preferences

​Fleet library catalog

​Library listings

​Startup

​Runners

​Runs

​Approvals

​Memory

​API keys

​Integration grants

​Credentials

​GitHub

​Connectors

​Related pages