Errors

The API uses conventional HTTP status codes. 2xx indicates success, 4xx indicates a problem with your request, and 5xx indicates a problem on our side or with an upstream provider.

Error shape

Errors return a JSON body with a detail field:

{ "detail": "This API key is missing the required scope 'vps:create'." }

Validation errors (malformed bodies) return FastAPI’s structured detail array describing each invalid field.

Status codes

Code	Meaning
200	Success.
201	Instance created.
400	Bad request — e.g. the action is not valid for this instance category.
401	Missing, invalid, revoked or expired API key.
402	Payment required — wallet balance too low to complete a create/resize.
403	The API key lacks the required scope.
404	Resource not found, or not owned by you.
409	Conflict — e.g. snapshot quota reached, current plan selected, or the server is busy with another task (retry shortly).
422	Validation error — a field is missing or malformed.
429	Rate limit exceeded. See Rate limits.
502	An upstream provider operation failed. Safe to retry after a moment.
503	A resource is temporarily unavailable (e.g. VNC while the server is off).

Provisioning is asynchronous

A 201 from POST /instances means the order was accepted and charged — not that the server is fully booted. Poll GET /instances/{id} until provider_id and ipv4 are populated.

Tips

• Always check the status code, not just the body.
• Log the detail message — it is human-readable and explains what to fix.
• Treat 5xx as transient and retry with backoff.