Successful answers
One object:
{"data": {"id": 219, "name": "web-1", "status": "active"}}A list, with its size in meta:
{"data": [{"id": 219}, {"id": 220}], "meta": {"total": 2}}Some changes add a meta block about what just happened, for example how much was charged:
{"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:
{"error": {"code": "node_unavailable", "message": "The server node is temporarily unavailable."}}codeis stable and machine-readable: build your logic on it and on the HTTP status.messageis 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:
{
"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.