API

Responses and errors

Оновлено 15 листопада 2026

Цю сторінку ще не перекладено вашою мовою, тому показано англійську версію.

На цій сторінці

Successful answers

One object:

JSON
{"data": {"id": 219, "name": "web-1", "status": "active"}}

A list, with its size in meta:

JSON
{"data": [{"id": 219}, {"id": 220}], "meta": {"total": 2}}

Some changes add a meta block about what just happened, for example how much was charged:

JSON
{"data": {"id": 219, "status": "active"}, "meta": {"charged": "5.00000000", "currency": "EUR"}}

An order answers 201 Created; everything else that succeeds answers 200 OK.

Errors

Every error has the same shape, whatever went wrong:

JSON
{"error": {"code": "node_unavailable", "message": "The server node is temporarily unavailable."}}
  • code is stable and machine-readable: build your logic on it and on the HTTP status.
  • message is always in English, meant for logs and people, and its wording may be improved at any time.

A validation error also lists the problems per field:

JSON
{
  "error": {
    "code": "invalid_input",
    "message": "The given data was invalid.",
    "fields": {"action": ["The selected action is invalid."]}
  }
}

fields is there when the request itself is malformed (a missing field, a wrong type, a weak password). When the values are well-formed but cannot be used, for example a system that the chosen location does not install, the code is the same invalid_input and message explains it, without fields.

A rate limit error usually comes with a Retry-After header, in seconds. The hourly limits of single actions answer without it, and message says how long to wait. See Rate limits.

Error codes

Code HTTP When
bad_request 400 the request is malformed
unauthenticated 401 no token, or the token is unknown, revoked or expired
insufficient_funds 402 the balance is too low for the charge
forbidden 403 the token lacks the ability, the IP address is not allowed, the account has no API access, is blocked or not verified
not_found 404 the server does not exist, is not yours or is deleted; unknown path
method_not_allowed 405 the path exists, but not with this HTTP method
invalid_state 409 the server is not in a status that allows this action (for example, not active)
not_supported 409 the action is not available for this server (for example, no backup storage on its location, or managing backups without the backup add-on)
busy 409 another operation is running on the server (a backup, a reinstall, an IP change): wait and retry
limit_reached 409 an account limit is used up: servers on this billing period, additional addresses
out_of_stock 409 nothing to give out right now: the plan is sold out in the location, or there are no free addresses. Usually temporary
payload_too_large 413 the request body is too large
too_early 425 a changing request arrived in TLS 1.3 early data (0-RTT), which can be replayed. Retry after the handshake; most HTTP clients do this on their own
invalid_input 422 validation failed; the details are in fields
rate_limited 429 too many requests, or an action repeated too soon. Wait for Retry-After when it is given
server_error 500 an error on our side. If it repeats, contact support
node_unavailable 503 the hardware node of the server is down or in maintenance
vm_unavailable 503 the virtual machine cannot be worked with right now, for example it is not created yet
api_disabled 503 the API is switched off for maintenance
server_unavailable 503 the service is temporarily unavailable

New codes may be added as the API grows; existing codes are never renamed. Treat an unknown code by its HTTP status.

What to retry

Answer What to do
429 rate_limited wait for Retry-After seconds, then retry. Without the header, wait at least a minute; for an hourly limit, as long as message says
409 busy retry later: the running operation will finish
503 node_unavailable, vm_unavailable, server_unavailable, api_disabled retry later with a growing delay
500 server_error a read can be retried; for a change, first read the server to see whether it was applied
4xx others do not retry unchanged: fix the request, the balance or the server's state

Be careful with retrying an order after a timeout: the first request may have succeeded. See Catalog and orders.

Питання щодо API?

Підтримка допоможе з інтеграцією та доступом.

Написати в підтримку