Error Handling
All errors follow a consistent format:{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable description of what went wrong."
}
}
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
| Status | Meaning |
|---|---|
200 | Success |
201 | Resource created |
204 | Success with no response body (delete operations) |
400 | Bad request — check the error message |
401 | Unauthenticated — invalid or missing token |
402 | Payment required — overdue invoices |
403 | Forbidden — account banned or IP not whitelisted |
404 | Resource not found |
409 | Conflict — server is in a state that prevents this action |
422 | Validation error — check the details object |
429 | Rate limited — too many requests |
500 | Internal server error |
Common Error Codes
Authentication
| Code | Description |
|---|---|
UNAUTHENTICATED | Missing Authorization: Bearer header |
INVALID_TOKEN | API token not found |
ACCOUNT_BANNED | Account is suspended |
IP_NOT_ALLOWED | Request IP not in whitelist |
Server Operations
| Code | Description |
|---|---|
SERVER_STATUS_CONFLICT | Server is busy (installing, restoring, etc.) |
NO_AVAILABLE_NODE | No node has capacity + matching template + available IPs |
RESOURCE_LIMIT_EXCEEDED | CPU or RAM limit reached |
OVERDUE_INVOICE | Must pay overdue invoices first |
PLAN_UNAVAILABLE | Plan is hidden |
PLAN_OUT_OF_STOCK | Plan stock is depleted |
NEW_USERS_ONLY | Plan restricted to first-time users |
TEMPLATE_NOT_FOUND | Template slug not available on the server’s node |
IP Operations
| Code | Description |
|---|---|
IP_LIMIT_REACHED | Account IP limit reached |
SERVER_IP_LIMIT | Per-server IP limit reached |
NO_IPS_AVAILABLE | No IPs available in the pool |
CANNOT_REMOVE_PRIMARY | Cannot remove the primary IPv4/IPv6 |
RATE_LIMITED | Too many IP add/remove operations this week |
Security Groups
| Code | Description |
|---|---|
HAS_SERVERS | Must detach all servers before deleting a group |
ALREADY_ATTACHED | Server is already in this security group |