Error Codes

Response format

Every 4xx and 5xx response uses Content-Type: application/problem+json:

{
  "docs_uri": "https://docs.usezombie.com/api-reference/error-codes#UZ-ZMB-009",
  "title": "Zombie not found",
  "detail": "No zombie with id 'abc123' in this workspace.",
  "error_code": "UZ-ZMB-009",
  "request_id": "req_a1b2c3d4e5f6"
}

Field	Description
`docs_uri`	Stable link to this page for the specific code
`title`	Short label — identical for every occurrence of a given code
`detail`	Instance-specific context (varies per call)
`error_code`	Machine-readable code. Use this for programmatic handling.
`request_id`	Correlation ID for support and log tracing

UUID validation

Code	HTTP	Title	Common Causes
`UZ-UUIDV7-003`	400	Invalid UUID canonical format	ID passed is not a valid canonical UUIDv7 string
`UZ-UUIDV7-005`	500	ID generation failed	Internal failure generating a new UUIDv7
`UZ-UUIDV7-009`	400	Invalid ID shape	Path or body ID does not match UUIDv7 format
`UZ-UUIDV7-010`	409	UUID backfill conflict	Duplicate ID detected during backfill
`UZ-UUIDV7-011`	500	Rollback blocked	Rollback cannot proceed due to existing state
`UZ-UUIDV7-012`	500	Error response linking failed	Internal error linking error response to trace

Internal errors

Code	HTTP	Title	Common Causes
`UZ-INTERNAL-001`	503	Database unavailable	Database server unreachable. Check `DATABASE_URL`.
`UZ-INTERNAL-002`	500	Database error	Query failed. Check DB logs.
`UZ-INTERNAL-003`	500	Internal operation failed	Unexpected internal failure. Check `err=` in logs.

Request validation

Code	HTTP	Title	Common Causes
`UZ-REQ-001`	400	Invalid request	Missing or malformed field in request body or query
`UZ-REQ-002`	413	Payload too large	Request body exceeds 2MB limit

Authentication / authorization

Code	HTTP	Title	Common Causes
`UZ-AUTH-001`	403	Forbidden	Token valid but lacks permission for this resource
`UZ-AUTH-002`	401	Unauthorized	Missing or invalid Bearer token
`UZ-AUTH-003`	401	Token expired	JWT has passed its expiry time. Re-authenticate.
`UZ-AUTH-004`	503	Authentication service unavailable	OIDC provider unreachable
`UZ-AUTH-005`	404	Session not found	Auth session ID not found or already expired
`UZ-AUTH-006`	401	Session expired	Auth session timed out before completion
`UZ-AUTH-007`	409	Session already complete	Auth session was already resolved
`UZ-AUTH-008`	503	Session limit reached	Too many concurrent auth sessions. Retry shortly.
`UZ-AUTH-009`	403	Insufficient role	Token role is too low for this endpoint
`UZ-AUTH-010`	403	Unsupported role	Token contains an unrecognized role claim

API / queue

Code	HTTP	Title	Common Causes
`UZ-API-001`	503	API saturated	Too many in-flight requests. Back off and retry.
`UZ-API-002`	503	Queue unavailable	Redis queue is unreachable

Workspace

Code	HTTP	Title	Common Causes
`UZ-WORKSPACE-001`	404	Workspace not found	No workspace with this ID exists
`UZ-WORKSPACE-002`	402	Workspace paused	Workspace billing is paused. Update payment.
`UZ-WORKSPACE-003`	402	Workspace free limit reached	Free-tier execution limit reached. Upgrade plan.

Billing

Code	HTTP	Title	Common Causes
`UZ-BILLING-001`	400	Invalid subscription ID	Subscription ID format is invalid
`UZ-BILLING-002`	500	Billing state missing	Workspace has no billing record
`UZ-BILLING-003`	500	Billing state invalid	Workspace billing record is in an inconsistent state
`UZ-BILLING-004`	400	Invalid billing event	Billing webhook payload is malformed or unknown
`UZ-BILLING-005`	402	Credit exhausted	Workspace has no remaining execution credit

Scoring

Code	HTTP	Title	Common Causes
`UZ-SCORING-001`	400	Invalid scoring context	Scoring context tokens are invalid. Check the context_tokens field.

Entitlement

Code	HTTP	Title	Common Causes
`UZ-ENTL-001`	503	Entitlement service unavailable	Could not verify plan entitlements
`UZ-ENTL-003`	402	Stage limit reached	Plan does not allow more pipeline stages
`UZ-ENTL-004`	403	Skill not allowed	Plan does not include this skill

Pipeline v1 removed

Code	HTTP	Title	Common Causes
`UZ-RUNS-410`	410	Pipeline v1 permanently removed	Pipeline v1 has been permanently removed. All `/v1/runs/*` and `/v1/specs` endpoints return 410 Gone. Use the zombie event model instead.

Agent

Code	HTTP	Title	Common Causes
`UZ-AGENT-001`	404	Agent not found	No agent profile with this ID

Profile

Code	HTTP	Title	Common Causes
`UZ-PROFILE-001`	404	Profile not found	Profile not found. Verify the profile_id.
`UZ-PROFILE-002`	400	Invalid profile	Profile data is invalid. Check required fields.

Webhook

Code	HTTP	Title	Common Causes
`UZ-WH-001`	404	Zombie not found for webhook	Webhook routing found no matching zombie
`UZ-WH-002`	400	Malformed webhook	Webhook body is missing required fields
`UZ-WH-003`	403	Zombie paused	Zombie exists but is not active
`UZ-WH-010`	401	Invalid webhook signature	Slack signature verification failed
`UZ-WH-011`	401	Stale webhook timestamp	Slack timestamp is >5 min old (replay protection)

Tool

Code	HTTP	Title	Common Causes
`UZ-TOOL-001`	424	Tool credential missing	Required vault credential not found for skill
`UZ-TOOL-002`	502	Tool API call failed	External API returned an error
`UZ-TOOL-003`	502	Tool git operation failed	Git operation failed. Check repo URL and credentials.
`UZ-TOOL-004`	400	Tool not attached	Tool name not in zombie’s TRIGGER.md skills list
`UZ-TOOL-005`	400	Unknown tool	Tool name not recognized
`UZ-TOOL-006`	504	Tool call timed out	External tool did not respond within timeout

Zombie

Code	HTTP	Title	Common Causes
`UZ-ZMB-001`	402	Zombie budget exceeded	Daily dollar budget hit. Raise via `zombiectl config set`.
`UZ-ZMB-002`	500	Zombie agent timeout	Agent timed out processing an event. Check logs.
`UZ-ZMB-003`	424	Zombie credential missing	Required vault credential absent. Use `zombiectl credential add`.
`UZ-ZMB-004`	500	Zombie claim failed	Could not claim zombie from DB. Verify zombie status.
`UZ-ZMB-005`	500	Zombie checkpoint failed	Session checkpoint write to Postgres failed
`UZ-ZMB-006`	409	Zombie name already exists	Name taken. Kill existing zombie first.
`UZ-ZMB-007`	400	Zombie credential value too long	Credential value exceeds 4KB limit
`UZ-ZMB-008`	400	Invalid zombie config	TRIGGER.md config_json fails schema validation
`UZ-ZMB-009`	404	Zombie not found	No zombie with this ID in the workspace

Gate

Code	HTTP	Title	Common Causes
`UZ-GATE-001`	500	Gate command failed	A gate command (make lint/test/build) failed. Check the gate results for stdout/stderr output.
`UZ-GATE-002`	504	Gate command timed out	A gate command exceeded its timeout. Increase GATE_TOOL_TIMEOUT_MS or optimize the command.
`UZ-GATE-003`	500	Gate repair attempts exhausted	Agent exhausted all repair attempts without passing gates. Review gate results for the repeated failure pattern.
`UZ-GATE-004`	500	Gate persist failed	Gate results could not be written to the database. Check DB connectivity and that the gate_results table exists.

Approval gate

Code	HTTP	Title	Common Causes
`UZ-APPROVAL-001`	400	Approval parse failed	`gates` in TRIGGER.md config_json has invalid JSON
`UZ-APPROVAL-002`	404	Approval not found	Approval action not found or already resolved
`UZ-APPROVAL-003`	401	Approval invalid signature	Slack signature or timestamp verification failed
`UZ-APPROVAL-004`	503	Approval Redis unavailable	Gate service down; default-deny applied
`UZ-APPROVAL-005`	400	Approval condition invalid	Gate condition expression is invalid

Credentials

Code	HTTP	Title	Common Causes
`UZ-CRED-001`	503	Anthropic API key missing	Workspace `anthropic_api_key` not in vault. Set via credentials API.
`UZ-CRED-002`	503	GitHub token failed	GitHub App token request failed. Check `GITHUB_APP_ID`.
`UZ-CRED-003`	503	Platform LLM key missing	No active platform LLM key. Admin must set via platform-keys API.

Relay

Code	HTTP	Title	Common Causes
`UZ-RELAY-001`	400	No LLM provider configured	Workspace has no LLM credentials configured

Startup

Code	HTTP	Title	Common Causes
`UZ-STARTUP-001`	500	Environment check failed	Required environment variables are missing. Run ‘zombied doctor’ to see which ones.
`UZ-STARTUP-002`	500	Config load failed	Configuration failed to load. Check that all required env vars are set.
`UZ-STARTUP-003`	500	Database connect failed	Database is unreachable. Check that DATABASE_URL is set and the database accepts connections.
`UZ-STARTUP-004`	500	Redis connect failed	Redis is unreachable. Check that REDIS_URL_API and REDIS_URL_WORKER are set.
`UZ-STARTUP-005`	500	Migration check failed	Database migration state could not be verified. Check DB connectivity.
`UZ-STARTUP-006`	500	OIDC init failed	OIDC provider initialization failed. Check OIDC configuration.
`UZ-STARTUP-007`	500	Redis group creation failed	Redis connected but consumer group creation failed. Check Redis ACL permissions.

Sandbox

Code	HTTP	Title	Common Causes
`UZ-SANDBOX-001`	503	Sandbox backend unavailable	Sandbox backend is not available. Check that bubblewrap (bwrap) is installed.
`UZ-SANDBOX-002`	403	Sandbox kill switch triggered	Sandbox kill switch has been triggered. Contact the administrator.
`UZ-SANDBOX-003`	403	Sandbox command blocked	The command is blocked by sandbox policy.

Executor

Code	HTTP	Title	Common Causes
`UZ-EXEC-001`	500	Execution session create failed	Execution session creation failed. Check runner availability.
`UZ-EXEC-002`	500	Stage start failed	Stage failed to start. Check runner configuration.
`UZ-EXEC-003`	500	Execution timeout kill	Execution exceeded the timeout limit and was killed.
`UZ-EXEC-004`	500	Execution OOM kill	Execution exceeded memory limit and was killed.
`UZ-EXEC-005`	500	Execution resource kill	Execution exceeded resource limits and was killed.
`UZ-EXEC-006`	500	Execution transport loss	Connection to execution transport was lost.
`UZ-EXEC-007`	500	Execution lease expired	Execution lease expired. The task took too long to complete.
`UZ-EXEC-008`	403	Execution policy deny	Execution was denied by policy. Check firewall rules.
`UZ-EXEC-009`	500	Execution startup posture failure	Execution startup posture check failed. Verify runner security config.
`UZ-EXEC-010`	500	Execution crash	The execution process crashed. Check logs for details.
`UZ-EXEC-011`	403	Landlock policy deny	Landlock policy denied the filesystem operation.
`UZ-EXEC-012`	500	Runner agent init failed	Runner agent initialization failed. Check configuration.
`UZ-EXEC-013`	500	Runner agent run failed	Runner agent execution failed. Check logs for details.
`UZ-EXEC-014`	400	Runner invalid config	Runner configuration is invalid. Check config_json fields.

Slack plugin

Code	HTTP	Title	Common Causes
`UZ-SLACK-001`	403	Slack OAuth state invalid	OAuth state parameter mismatch — possible CSRF attempt.
`UZ-SLACK-002`	502	Slack token exchange failed	Could not exchange OAuth code for bot token. Verify SLACK_CLIENT_SECRET is set.
`UZ-SLACK-003`	401	Slack bot token expired	The Slack bot token has been revoked or expired. Reinstall UseZombie to Slack.

Overview

Health

Authentication

Workspaces

Runs

Credentials

Skill Secrets

Admin

Billing

Response format

UUID validation

Internal errors

Request validation

Authentication / authorization

API / queue

Workspace

Billing

Scoring

Entitlement

Pipeline v1 removed

Agent

Profile

Webhook

Tool

Zombie

Gate

Approval gate

Credentials

Relay

Startup

Sandbox

Executor

Slack plugin

Overview

Health

Authentication

Workspaces

Runs

Credentials

Skill Secrets

Admin

Billing

​Response format

​UUID validation

​Internal errors

​Request validation

​Authentication / authorization

​API / queue

​Workspace

​Billing

​Scoring

​Entitlement

​Pipeline v1 removed

​Agent

​Profile

​Webhook

​Tool

​Zombie

​Gate

​Approval gate

​Credentials

​Relay

​Startup

​Sandbox

​Executor

​Slack plugin

Response format

UUID validation

Internal errors

Request validation

Authentication / authorization

API / queue

Workspace

Billing

Scoring

Entitlement

Pipeline v1 removed

Agent

Profile

Webhook

Tool

Zombie

Gate

Approval gate

Credentials

Relay

Startup

Sandbox

Executor

Slack plugin