Skip to main content

Error Handling

All errors follow a consistent format:
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong."
  }
}
Validation errors include a details object with per-field messages:
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid.",
    "details": {
      "plan_id": ["The plan id field is required."],
      "template_slug": ["The template slug field is required."]
    }
  }
}

HTTP Status Codes

StatusMeaning
200Success
201Resource created
204Success with no response body (delete operations)
400Bad request — check the error message
401Unauthenticated — invalid or missing token
402Payment required — overdue invoices
403Forbidden — account banned or IP not whitelisted
404Resource not found
409Conflict — server is in a state that prevents this action
422Validation error — check the details object
429Rate limited — too many requests
500Internal server error

Common Error Codes

Authentication

CodeDescription
UNAUTHENTICATEDMissing Authorization: Bearer header
INVALID_TOKENAPI token not found
ACCOUNT_BANNEDAccount is suspended
IP_NOT_ALLOWEDRequest IP not in whitelist

Server Operations

CodeDescription
SERVER_STATUS_CONFLICTServer is busy (installing, restoring, etc.)
NO_AVAILABLE_NODENo node has capacity + matching template + available IPs
RESOURCE_LIMIT_EXCEEDEDCPU or RAM limit reached
OVERDUE_INVOICEMust pay overdue invoices first
PLAN_UNAVAILABLEPlan is hidden
PLAN_OUT_OF_STOCKPlan stock is depleted
NEW_USERS_ONLYPlan restricted to first-time users
TEMPLATE_NOT_FOUNDTemplate slug not available on the server’s node

IP Operations

CodeDescription
IP_LIMIT_REACHEDAccount IP limit reached
SERVER_IP_LIMITPer-server IP limit reached
NO_IPS_AVAILABLENo IPs available in the pool
CANNOT_REMOVE_PRIMARYCannot remove the primary IPv4/IPv6
RATE_LIMITEDToo many IP add/remove operations this week

Security Groups

CodeDescription
HAS_SERVERSMust detach all servers before deleting a group
ALREADY_ATTACHEDServer is already in this security group