Error Codes

All error responses use this envelope:

{
  "error": "error_code",
  "message": "Human-readable description.",
  "requestId": "abc123-def456"
}

The error field is a stable, machine-readable code. The message is for display and may change between releases. The requestId correlates with server-side logs.

General errors

Code	HTTP	Description
`not_found`	404	Resource does not exist
`forbidden`	403	Caller lacks RBAC permissions
`unauthorized`	401	Authentication missing or invalid
`conflict`	409	Resource version conflict (optimistic concurrency)
`already_exists`	409	Resource being created already exists
`bad_request`	400	Malformed request or invalid parameters
`internal_error`	500	Unexpected server failure. Check logs with `requestId`
`timeout`	504	Operation exceeded deadline
`method_not_allowed`	405	HTTP method not supported

Input validation errors

Code	HTTP	Description
`invalid_parameter`	400	Query or path parameter has invalid value
`missing_path_param`	400	Required path parameter absent
`missing_query_param`	400	Required query parameter absent
`invalid_namespace`	400	Namespace fails K8s name validation
`invalid_name`	400	Resource name fails K8s name validation
`invalid_path_params`	400	Dynamic handler path variables invalid
`invalid_input`	400	User input fails validation
`invalid_body`	400	Request body cannot be decoded
`invalid_json`	400	Body is not valid JSON
`missing_field`	400	Required field missing
`invalid_field`	400	Field has invalid value
`body_too_large`	413	Body exceeds size limit
`invalid_propagation`	400	Invalid deletion propagation policy

Kubernetes errors

Code	HTTP	Description
`api_unreachable`	502	K8s API server unreachable
`context_not_found`	404	Kubeconfig context does not exist
`context_switch_failed`	500	Context switch failed
`context_list_failed`	500	Context enumeration failed
`invalid_context`	400	Context cannot be resolved
`insufficient_permissions`	403	User lacks RBAC permissions in target cluster
`source_fetch_failed`	502	Cross-cluster source fetch failed
`target_fetch_failed`	502	Cross-cluster target fetch failed

Helm errors

Code	HTTP	Description
`helm_not_found`	500	`helm` binary not on `$PATH`
`helm_error`	500	Helm CLI command failed
`invalid_revision`	400	Invalid Helm revision number

Infrastructure errors

Code	HTTP	Description
`drain_in_progress`	409	Drain already running on node
`dependency_unavailable`	503	External dependency not reachable
`too_many_contexts`	400	Contexts exceed maximum (50)

Client handling

Safe to retry

api_unreachable - K8s API may be temporarily down
timeout - May succeed on retry
internal_error - Transient server failure

Use exponential backoff with jitter.

Do not retry

forbidden / unauthorized - Fix authentication
not_found - Resource doesn’t exist
invalid_* / missing_* - Fix the request
conflict - Re-fetch and retry with updated version