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 |
IP_NOT_FOUND | The address is not on this server |
RATE_LIMITED | Too many IP add/remove operations this week |
Reserved IPs
| Code | Description |
|---|---|
RESERVED_IP_NOT_FOUND | The address is not one of your reserved IPs |
RESERVED_IP_IN_USE | The reserved IP is already on a server |
RESERVED_IP_WRONG_NODE | The reserved IP is routed to a different node than the server |
RESERVED_IP_LOCATION_MISMATCH | The reserved IPs cannot be used together at that location |
RESERVED_IP_LIMIT_REACHED | Your account IP limit (server and reserved IPs together) is reached |
RESERVED_IP_IPV6_UNSUPPORTED | The template has no IPv6, so reserved IPv6 addresses cannot be used |
INVALID_MAIN_IP | main_ipv4 / main_ipv6 is neither new nor one of reserved_ips |
SUBNET_EXHAUSTED | The subnet has fewer free addresses than requested |
INSUFFICIENT_BALANCE | Your balance does not cover the first hour |
INVALID_KEEP_IPS | keep_ips names an address that is not on the server |
LOCATION_NOT_FOUND | The location does not exist |
Security Groups
| Code | Description |
|---|---|
HAS_SERVERS | Must detach all servers before deleting a group |
ALREADY_ATTACHED | Server is already in this security group |
Workers
| Code | Description |
|---|---|
WORKERS_DISABLED | Worker sales are currently turned off |
LOCATION_UNAVAILABLE | That location cannot take a worker |
INSUFFICIENT_BALANCE | Balance is below one hour at your container caps |
DEPOSIT_REQUIRED | First-time accounts must top up before deploying |
OVERDUE_INVOICE | Must pay overdue invoices first |
WORKER_LIMIT_REACHED | Account level allows no further workers |
GITHUB_NOT_CONNECTED | Link GitHub in the panel before deploying a private repository |
INVALID_WORKER_CONFIG | Unknown template, or a repository the build cannot use |
WORKER_STATE_CONFLICT | Worker is not in a state this action can run from |
CONFIRMATION_MISMATCH | confirmation does not match the worker name |
TEMPLATE_CATALOG_UNAVAILABLE | The one-click template catalog could not be read |
WORKER_ERROR | The platform refused the action; see the message |