API Reference

Technical reference information for the Suble.io API v2.

Error Responses

All API endpoints return consistent error responses with descriptive messages.

Status Code	Description
200	Success - Request completed successfully
400	Bad Request - Invalid request parameters or missing required fields
401	Unauthorized - Missing or invalid authentication token
403	Forbidden - Insufficient permissions for the requested operation
404	Not Found - The requested resource does not exist
500	Internal Server Error - An unexpected error occurred on the server

All error responses follow this consistent format:

{
  "error": "Descriptive error message explaining what went wrong"
}

Some endpoints require specific permissions. Common permission-based error:

{
  "error": "Insufficient permissions to access this resource"
}

Error Message	Cause	Solution
"Invalid fullname, email, password or country"	Registration validation failed	Check all required fields are valid
"Invalid email or password."	Login credentials incorrect	Verify credentials and try again
"Project not found"	Project ID doesn't exist or no access	Check project ID and permissions
"Error, vps is already online."	VM already in requested state	Check VM status before operation
"Error, the vps must be offline to rebuild."	VM must be stopped for rebuild	Stop VM before rebuilding
"Error, only hourly billing can be deleted"	Subscription VMs cannot be deleted	Cancel subscription instead

API requests are subject to rate limiting to ensure fair usage and system stability.

If you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded. Please try again later."
}

All API responses include rate limiting information in the headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per time window
`X-RateLimit-Remaining`	Remaining requests in current window
`X-RateLimit-Reset`	Unix timestamp when the rate limit resets

Token Type	Purpose	Lifespan
Access Token	API requests	Short-lived (15-60 minutes)
Refresh Token	Renewing access tokens	Long-lived (30 days)

Different endpoints require different permission levels:

Permission	Description
`READ_VPS`	View VM information and status
`VPS_CONTROL`	Start, stop, reboot VMs
`WRITE_VPS`	Modify VM settings
`VPS_DELETE`	Delete or rebuild VMs
`READ_NETWORK`	View network configuration
`WRITE_NETWORK`	Modify network settings
`READ_FIREWALL`	View firewall rules
`WRITE_FIREWALL`	Modify firewall rules
`CONSOLE_VNC`	Access VM console
`READ_MEMBERS`	View project members
`WRITE_MEMBERS`	Manage project members
`READ_SSHKEYS`	View SSH keys
`WRITE_SSHKEYS`	Manage SSH keys
`ORDER_PRODUCT`	Create and resize VMs