Error Codes - usezombie

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-009`	400	Invalid ID shape	Path or body ID does not match UUIDv7 format

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

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	Run limit reached	Plan does not allow more pipeline runs
`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 agent event model instead.

Webhook

Code	HTTP	Title	Common Causes
`UZ-WH-001`	404	Agent not found for webhook	Webhook routing found no matching agent
`UZ-WH-002`	400	Malformed webhook	Webhook body is missing required fields
`UZ-WH-003`	403	Agent paused	Agent exists but is not active
`UZ-WH-010`	401	Invalid webhook signature	HMAC or Svix signature verification failed. Verify the `secret_ref` vault entry matches the signing secret configured with the provider.
`UZ-WH-011`	401	Stale webhook timestamp	Webhook timestamp is older than 5 minutes (replay protection). Ensure the sender clock is not skewed.
`UZ-WH-020`	401	Webhook credential not configured	No webhook credential is configured for this agent’s source. Run `zombiectl credential add <source> --data=@-` with `{ "webhook_secret": "..." }` in the agent’s workspace, then resend.
`UZ-WH-030`	413	Webhook payload too large	Webhook body exceeds the 1 MiB ingest limit. Reduce the payload at the source or filter fields before forwarding.

Tool

Code	HTTP	Title	Common Causes
`UZ-TOOL-004`	400	Tool not attached	The tool isn’t in this agent’s `tools:` list. Add it to `TRIGGER.md` `x-usezombie.tools:` and re-install.
`UZ-TOOL-005`	400	Unknown tool	Tool name not recognized — typo against the Tools catalogue is the usual cause.

Registered, not always emitted. The two UZ-TOOL-* codes are registered in the platform’s error registry but, in v2 today, the user-facing failure path for a missing or misspelled tool is a NullClaw-level “no such tool” message in the activity stream rather than one of these wire codes. Treat the codes as authoritative for meaning if you do see them, but don’t expect them as the primary signal — audit zombiectl logs <zombie_id> for the actual error text.

Agent

Code	HTTP	Title	Common Causes
`UZ-ZMB-001`	402	Agent budget exceeded	Daily dollar budget hit. Raise `budget.daily_dollars` in `TRIGGER.md`.
`UZ-ZMB-002`	500	Agent agent timeout	Agent timed out processing an event. Check the activity stream.
`UZ-ZMB-003`	424	Agent credential missing	A required vault credential is absent. Add it with `zombiectl credential add <name>`.
`UZ-ZMB-004`	500	Agent claim failed	Agent could not be claimed from the database. Verify the `zombie_id` exists and status is `active`.
`UZ-ZMB-005`	500	Agent checkpoint failed	Session checkpoint write to Postgres failed.
`UZ-ZMB-006`	409	Agent name already exists	Name taken. Kill the existing agent first, then re-install.
`UZ-ZMB-008`	400	Invalid agent config	`TRIGGER.md` config_json fails schema validation. Verify trigger, tools, credentials, and budget fields.
`UZ-ZMB-009`	404	Agent not found	No agent with this ID in the workspace.
`UZ-ZMB-010`	409	Agent already stopped or killed	This agent is already stopped or killed. Re-install before issuing another stop.
`UZ-ZMB-011`	400	SKILL.md and TRIGGER.md disagree on `name:`	Top-level `name:` must match across both files. One identity per agent bundle.

UZ-ZMB-007 is retired; oversized credential bodies now return UZ-VAULT-002.

Integration grants

Code	HTTP	Title	Common Causes
`UZ-GRANT-001`	403	No integration grant for service	This agent has no approved grant for the target service. Request one with `POST /v1/zombies/{id}/integration-requests`.
`UZ-GRANT-002`	403	Integration grant pending approval	A grant request for this service is pending human approval. Approve in Slack, Discord, or the dashboard.
`UZ-GRANT-003`	403	Integration grant denied	The grant for this service was denied or revoked by the workspace owner. Re-request via the host agent.

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.

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

These fire on the inference path — when the runner needs to call the model and can’t resolve a usable LLM provider key. Not the same as workspace vault credentials your agent uses for http_request (those are UZ-VAULT-* and UZ-ZMB-003).

Code	HTTP	Title	Common Causes
`UZ-CRED-001`	503	Anthropic API key missing	Workspace LLM API key not found in `vault.secrets` (key: `anthropic_api_key`). Set via the workspace credentials API, or set `ANTHROPIC_API_KEY` in the environment for dev.
`UZ-CRED-003`	503	Platform LLM key missing	No active platform-managed LLM key for the resolved provider. The platform admin must rotate the key, or your tenant must attach its own via the workspace credentials API.

Vault

Code	HTTP	Title	Common Causes
`UZ-VAULT-001`	400	Credential data must be a non-empty JSON object	`POST /credentials` body must include a `data` field that is a JSON object with at least one key. Bare strings, arrays, scalars, and `{}` are rejected.
`UZ-VAULT-002`	400	Credential data too large	Stringified credential data exceeds 4 KB. Compose the secret from fewer or shorter fields.

Memory

Code	HTTP	Title	Common Causes
`UZ-MEM-001`	403	Memory scope denied	Cross-agent memory access attempted. Memory operations are scoped per `zombie_id`.
`UZ-MEM-002`	404	Agent not found for memory op	The `zombie_id` on the memory call does not exist in the workspace.
`UZ-MEM-003`	503	Memory backend unavailable	Memory store is unreachable. Retry the trigger; if persistent, file an issue.

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 is set.
`UZ-STARTUP-005`	500	Migration check failed	Database migration state could not be verified. Check DB connectivity.
`UZ-STARTUP-007`	500	Redis group creation failed	Redis connected but consumer group creation failed. Check Redis ACL permissions.

Runner

Code	HTTP	Title	Common Causes
`UZ-EXEC-001`	500	Execution session create failed	Execution session creation failed. Check runner availability.
`UZ-EXEC-002`	500	Run start failed	Run failed to start. Check runner configuration.
`UZ-EXEC-003`	500	Execution timeout kill	Execution exceeded the timeout limit and was killed.
`UZ-EXEC-009`	500	Execution startup posture failure	Execution startup posture check failed. Verify runner security config.
`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.

​Response format

​UUID validation

​Internal errors

​Request validation

​Authentication / authorization

​Workspace

​Billing

​Scoring

​Entitlement

​Pipeline v1 removed

​Webhook

​Tool

​Agent

​Integration grants

​Gate

​Approval gate

​Credentials

​Vault

​Memory

​Relay

​Startup

​Runner

​Slack plugin

Response format

UUID validation

Internal errors

Request validation

Authentication / authorization

Workspace

Billing

Scoring

Entitlement

Pipeline v1 removed

Webhook

Tool

Agent

Integration grants

Gate

Approval gate

Credentials

Vault

Memory

Relay

Startup

Runner

Slack plugin