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:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "fields": {
        "name": "Name is required",
        "bmcAddress": "Invalid BMC address format"
      }
    }
  },
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z"
  }
}

Error Object Fields

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

HTTP Status Codes

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

Key Patterns

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

Common Error Codes

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

Error Examples

Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "fields": {
        "name": "Name is required",
        "region": "Invalid region code"
      }
    }
  },
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z"
  }
}

Not Found Error

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Server not found: srv_abc123"
  },
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z"
  }
}

Invalid State Transition

{
  "success": false,
  "error": {
    "code": "INVALID_STATE_TRANSITION",
    "message": "Cannot provision server in 'allocated' state",
    "details": {
      "currentState": "allocated",
      "requiredState": "available"
    }
  },
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z"
  }
}

Capacity Exceeded

{
  "success": false,
  "error": {
    "code": "POOL_CAPACITY_EXCEEDED",
    "message": "Not enough available servers in pool gpu-h100-pool",
    "details": {
      "poolId": "pool_abc123",
      "requested": 10,
      "available": 3
    }
  },
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z"
  }
}

Typed Error Classes

The k0rdent API implementation uses typed error classes for consistency:

AppError

Base error class for all application errors:

class AppError extends Error {
  constructor(
    public code: string,
    message: string,
    public statusCode: number = 500,
    public details?: unknown
  )
}

ValidationError

Used for request validation failures:

class ValidationError extends AppError {
  constructor(message: string, details?: unknown) {
    super('VALIDATION_ERROR', message, 400, details)
  }
}

NotFoundError

Used when a resource cannot be found:

class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super('NOT_FOUND', `${resource} not found: ${id}`, 404)
  }
}

ForbiddenError

Used when the user lacks permission:

class ForbiddenError extends AppError {
  constructor(message: string = 'Access denied') {
    super('FORBIDDEN', message, 403)
  }
}

ConflictError

Used for resource state conflicts:

class ConflictError extends AppError {
  constructor(message: string) {
    super('CONFLICT', message, 409)
  }
}

InvalidStateTransitionError

Used for invalid state transitions:

class InvalidStateTransitionError extends ConflictError {
  constructor(resource: string, currentState: string, targetState: string) {
    super(
      `Cannot transition ${resource} from ${currentState} to ${targetState}`
    )
    this.code = 'INVALID_STATE_TRANSITION'
  }
}

Bulk Operation Errors

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

{
  "success": true,
  "data": {
    "action": "power",
    "requested": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "id": "srv_123",
        "status": "success"
      },
      {
        "id": "srv_456",
        "status": "success"
      },
      {
        "id": "srv_789",
        "status": "failed",
        "error": {
          "code": "BMC_CONNECTION_FAILED",
          "message": "Cannot connect to BMC"
        }
      }
    ]
  },
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z"
  }
}

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

Error Handling Best Practices

For API Consumers

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

Example Client Code

const response = await fetch('/v1/region/sfo1/compute/clusters', {
  method: 'POST',
  body: JSON.stringify(data)
})

const json = await response.json()

if (!json.success) {
  console.error('Request failed:', {
    requestId: json.meta.requestId,
    code: json.error.code,
    message: json.error.message
  })
  
  // Handle specific errors
  switch (json.error.code) {
    case 'VALIDATION_ERROR':
      // Show validation errors to user
      break
    case 'POOL_CAPACITY_EXCEEDED':
      // Suggest different pool or region
      break
    default:
      // Generic error handling
  }
}

Rate Limiting

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

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 60 seconds."
  },
  "meta": {
    "requestId": "req_sfo1-1770564159296-7d4b9e1f3a5b",
    "timestamp": "2025-01-09T12:00:00.000Z"
  }
}

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

Platform APIs

Shared API Spec

Apps Team APIs Dev

Draft APIs

Archived APIs

Error Response Structure

Error Object Fields

HTTP Status Codes

Key Patterns

Common Error Codes

Error Examples

Validation Error

Not Found Error

Invalid State Transition

Capacity Exceeded

Typed Error Classes

AppError

ValidationError

NotFoundError

ForbiddenError

ConflictError

InvalidStateTransitionError

Bulk Operation Errors

Error Handling Best Practices

For API Consumers

Example Client Code

Rate Limiting

​Error Response Structure

​Error Object Fields

​HTTP Status Codes

​Key Patterns

​Common Error Codes

​Error Examples

​Validation Error

​Not Found Error

​Invalid State Transition

​Capacity Exceeded

​Typed Error Classes

​AppError

​ValidationError

​NotFoundError

​ForbiddenError

​ConflictError

​InvalidStateTransitionError

​Bulk Operation Errors

​Error Handling Best Practices

​For API Consumers

​Example Client Code

​Rate Limiting

Error Response Structure

Error Object Fields

HTTP Status Codes

Key Patterns

Common Error Codes

Error Examples

Validation Error

Not Found Error

Invalid State Transition

Capacity Exceeded

Typed Error Classes

AppError

ValidationError

NotFoundError

ForbiddenError

ConflictError

InvalidStateTransitionError

Bulk Operation Errors

Error Handling Best Practices

For API Consumers

Example Client Code

Rate Limiting