Error Taxonomy

Every error in the system maps to a category. This enables consistent handling across core and plugins.

Error Categories

Category	HTTP Status	When
validation	400	Bad input, missing fields, constraint violation
unauthorized	401	No token, expired token, invalid token
forbidden	403	Valid token, insufficient RBAC permissions
not_found	404	Entity doesn't exist
conflict	409	Duplicate name, version conflict
rate_limited	429	Too many requests
engine_error	502	Plugin engine returned an error
unavailable	503	Engine not loaded, database down, sealed
internal	500	Unexpected error -- logged with request_id

Engine error mapping: When plugin code returns an error, the engine executor translates it to the appropriate HTTP status. The mapping is defined in internal/engine/executor.go.

Error Response Format

All HTTP errors use this format:

{
    "error": "engine 'pg-prod' not found — list engines with: arcan engine list -r <realm>",
    "code": "not_found",
    "request_id": "req_abc123"
}

For 500 errors, add diagnostic fields:

{
    "error": "credential generation failed — check engine connectivity",
    "code": "internal",
    "request_id": "req_abc123",
    "report_url": "https://github.com/getarcan/arcan/issues/new?title=..."
}

Error Message Rules

All three questions must be answered in every error message:

1. What failed? -- the operation
2. Why? -- the likely cause
3. What now? -- the recovery action (include a CLI command when possible)