Errors

Common error codes and their meanings

The k0rdent API uses standard HTTP status codes and structured error responses to communicate failures clearly.

Error Response Structure

All error responses follow a consistent structure with the discriminated union envelope:

Field	Type	Description
`code`	string	Machine-readable error code
`message`	string	Human-readable error description
`details`	object	Additional context (optional)

The k0rdent API uses the following HTTP status codes:

Code	Usage
`200`	Success (GET, PATCH, DELETE)
`201`	Created (POST that creates resource)
`202`	Accepted (async operation started)
`204`	No Content (DELETE with no body)
`207`	Multi-Status (bulk operations)
`400`	Bad Request (validation error)
`401`	Unauthorized (no/invalid auth)
`403`	Forbidden (valid auth, no permission)
`404`	Not Found
`409`	Conflict (resource state conflict)
`422`	Unprocessable Entity (semantic error)
`429`	Too Many Requests (rate limited)
`500`	Internal Server Error

Use 202 Accepted for all async operations (BMC, K8s interactions)
Use 207 Multi-Status for all batch operations (indicates partial success possible)
Use 409 Conflict for invalid state transitions (e.g., provisioning an already-provisioned server)
Always include error codes in response body, not just HTTP status

The API uses machine-readable error codes in the error.code field:

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Request validation failed
`NOT_FOUND`	404	Resource not found
`FORBIDDEN`	403	Insufficient permissions
`UNAUTHORIZED`	401	Invalid or missing authentication
`CONFLICT`	409	Resource state conflict
`INVALID_STATE_TRANSITION`	409	Cannot transition resource to target state
`POOL_CAPACITY_EXCEEDED`	409	Not enough resources in pool
`QUOTA_EXCEEDED`	403	Organization quota exceeded
`BMC_CONNECTION_FAILED`	500	Cannot connect to BMC
`INTERNAL_ERROR`	500	Unexpected server error

The k0rdent API implementation uses typed error classes for consistency:

Base error class for all application errors:

Used for request validation failures:

Used when a resource cannot be found:

Used when the user lacks permission:

Used for resource state conflicts:

Used for invalid state transitions:

Bulk operations use 207 Multi-Status with per-resource error details:

Note: Bulk operations always return success: true at the top level, with per-resource status in the results array.

Check the success field - Use TypeScript discriminated unions for type safety
Log requestId - Always log the request ID for debugging
Handle specific error codes - Don't rely solely on HTTP status codes
Parse details field - Provides additional context for validation errors
Implement retries - For 500 and 429 errors with exponential backoff

Rate limit errors return 429 Too Many Requests with a Retry-After header indicating when to retry.

Check the Retry-After response header for the recommended retry delay in seconds.