Appendix B: API Error Codes

Code	HTTP Status	Description
`QUOTA_EXCEEDED`	429	Customer has exceeded workload quota
`INSUFFICIENT_CAPACITY`	503	No spot capacity available for requirements
`POLICY_BLOCKED`	403	Request blocked by Kivera policy
`INVALID_REQUIREMENTS`	400	Workload requirements cannot be satisfied
`WORKLOAD_NOT_FOUND`	404	Workload ID does not exist
`PROVIDER_ERROR`	502	Cloud provider API returned an error
`UNAUTHORIZED`	401	Invalid or expired authentication token
`FORBIDDEN`	403	Insufficient permissions for this operation
`RATE_LIMITED`	429	Too many requests, please slow down
`VALIDATION_ERROR`	400	Request body failed validation
`INTERNAL_ERROR`	500	Unexpected server error
`SERVICE_UNAVAILABLE`	503	Service temporarily unavailable
`WORKLOAD_ALREADY_TERMINATED`	400	Cannot perform action on terminated workload
`WORKLOAD_NOT_RUNNING`	400	Workload is not in RUNNING state
`DUPLICATE_WORKLOAD_NAME`	409	Workload name already exists for this customer
`INVALID_CLOUD_ACCOUNT`	400	Cloud account not configured or invalid
`CREDENTIAL_ERROR`	500	Failed to decrypt or use cloud credentials
`TIMEOUT`	504	Operation timed out

Error Response Format

All API errors return a consistent JSON structure:

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "You have reached your maximum of 100 concurrent workloads",
    "details": {
      "currentCount": 100,
      "maxAllowed": 100,
      "tier": "pro"
    },
    "requestId": "req_abc123def456"
  }
}

Handling Errors

Retry-able Errors

The following errors may be retried with exponential backoff:

PROVIDER_ERROR - Cloud provider may be temporarily unavailable
RATE_LIMITED - Wait for the Retry-After header duration
SERVICE_UNAVAILABLE - Platform is temporarily unavailable
TIMEOUT - Operation may have partially completed

Non-Retry-able Errors

These errors require user action or configuration changes:

QUOTA_EXCEEDED - Upgrade tier or terminate existing workloads
POLICY_BLOCKED - Review Kivera policies
INVALID_REQUIREMENTS - Adjust workload requirements
UNAUTHORIZED - Refresh or replace authentication token
FORBIDDEN - Request additional permissions