Errors and limits

The error format

Every error has the same body: a list of errors, each with a code naming the kind of error, the HTTP status as a string and a detail you can show to a person. Validation errors (422) have one entry per problem, and meta.source_field names the field at fault.

{
    "errors": [
        {
            "code": "ValidationException",
            "status": "422",
            "detail": "The signal field is required.",
            "meta": { "source_field": "signal", "rule": "required" }
        }
    ]
}

Status codes

200, 201, 202 and 204 mean it worked; 202 means it was accepted and finishes in the background. 400 means the request could not be carried out as sent, and the detail says why. 401 means the key is missing, wrong or expired. 403 means the key is fine but may not do this: it lacks a permission or scope, or it is limited to other IP addresses.

404 means there is no such thing, or the key cannot see it: a key limited to some servers gets 404 for the others, and features that are switched off answer 404 too. 409 means the server is busy, for example installing, restoring a backup or being deleted, or that you are at a limit. 422 means a field is missing or invalid. 429 means slow down. 502, 503 and 504 mean the node running the server could not be reached or had no room; try again shortly.

Rate limits

Each account may make 768 requests a minute across the API. Some endpoints have tighter limits of their own, shown on each one: creating servers, deploying, sharing logs and similar actions that do real work on a node.

Over a limit you get a 429 with a Retry-After header saying how many seconds to wait. Wait that long, then carry on. Polling a server more than once every few seconds gains nothing: the live console WebSocket pushes changes as they happen.

Account limits

An account may own 1 free server. Paid servers and servers you reach as a subuser do not count. Creating another free server over the limit gets a 409, whether you use the panel or the API.

An API key with the purchase scope may start 2 paid orders in any 24 hours. Orders made in the panel do not count. If you have a real need for more, ask us and we can raise it for your account.