Error Reference

Error categories, HTTP status codes, and troubleshooting hints.

HTTP Status Codes

Error Categories

ValidationError

Invalid configuration or request data.

{
  "error": {
    "category": "ValidationError",
    "message": "server.listen '...' is not a valid socket address"
  }
}

Common causes:

• Invalid config.toml fields (see validation rules)
• Missing required fields in API requests
• Invalid semver constraint in package dependencies

AuthenticationError

Request could not be authenticated.

{
  "error": {
    "category": "AuthenticationError",
    "message": "Invalid or expired API key"
  }
}

Troubleshoot: Check API key validity, expiration, and correct header format (Authorization: Bearer hzk_...).

AuthorizationError

Authenticated but insufficient permissions.

{
  "error": "forbidden",
  "message": "Role 'viewer' is not authorized for action 'agent:create'"
}

Troubleshoot: Check the role assigned to your key. See RBAC.

ProviderError

LLM provider returned an error or is unreachable.

Sub-types:

• ProviderAuthFailed — invalid API key at the provider
• ProviderUnavailable — network error or timeout
• CircuitBreakerOpen — too many consecutive failures
• RateLimited — provider returned 429

Troubleshoot: See provider troubleshooting.

AgentError

Agent lifecycle or execution error.

Sub-types:

• InvalidStateTransition — e.g., starting an already-running agent
• AgentNotFound — referenced agent doesn't exist
• ExecutionTimeout — agent execution exceeded timeout

Troubleshoot: See agent troubleshooting.

WorkflowError

Workflow execution failure.

Sub-types:

• StepTimeout — a step exceeded its timeout
• AgentNotFound — workflow references a deleted agent
• StepFailed — a step returned an error (respecting error_mode)

PackageError

Catalog or package operation failure.

Sub-types:

• SignatureMismatch — package signature verification failed
• ContentHashMismatch — payload was modified after signing
• VersionConflict — incompatible dependency versions
• CycleDetected — circular dependency
• PackageNotFound — package not in any configured registry

MemoryError

Memory subsystem issue.

Sub-types:

• MemoryViolation — cross-agent memory access attempted
• SubsystemDegraded — SQLite connectivity issue

Troubleshoot: See troubleshooting recovery.

Related:

• Troubleshooting
• RBAC
• Provider troubleshooting