Error Codes

All errors from the hzel API follow the same envelope. See Response Format for the full structure.

Code reference

UNAUTHORIZED — 401

No valid credentials were found on the request. Either include a Authorization: Bearer <token> header, or ensure your session cookie is valid and not expired.

FORBIDDEN — 403

Credentials are valid but the authenticated account does not have permission to perform the action. Common reasons:

• Accessing another user’s container without admin role.
• Using an OAuth application token on an endpoint that requires a direct user session (e.g. token management).

CSRF_REJECTED — 403

The x-csrf-token header is missing or doesn’t match the session’s token. See CSRF Protection for how to obtain and send this header.

VALIDATION_FAILED — 400

A field in the request body or query string failed a validation rule. The message field will indicate which field and why. Examples:

• "disk_gb must be between 18 and 32"
• "At least one redirect URI is required"
• "response_type must be \"code\""

BAD_REQUEST — 400

The request was structurally invalid (e.g. malformed JSON, missing required field with no specific validation rule).

NOT_FOUND — 404

The generic not-found code. Returned when a resource doesn’t exist or — for ownership-guarded resources — when the requesting user doesn’t own it (to avoid leaking existence).

CONTAINER_NOT_FOUND — 404

Specific to container endpoints. The message includes the requested container ID:

{ "error": { "code": "CONTAINER_NOT_FOUND", "message": "Container abc123 was not found" } }

COMMAND_NOT_FOUND — 404

Specific to the command job endpoints. The message includes the requested job ID.

NOT_IMPLEMENTED — 501

The endpoint exists in the API but the feature is disabled in the current deployment configuration (e.g. OIDC login when OIDC is not configured).

INTERNAL_ERROR — 500

An unexpected server-side error. If you encounter this consistently, contact support with the request details and timestamp.