API / Getting started / Errors and status codes

Errors and status codes

Error response

Field	Type	Meaning
`status`	number	The HTTP status
`code`	string	A short code for programs, e.g. `token_scope_missing`. Go by this
`error`	string	An English description for people. The wording may change
`requestId`	string	The request's ID, the same as the `X-Request-ID` header. Include it in a support ticket so we find your request fast

Example:

HTTP

HTTP/2 403 Forbidden
{
  "status": 403,
  "code": "token_scope_missing",
  "error": "this API token lacks the servers:power scope",
  "requestId": "3f1c9a2e-7b4d-4e8a-9c21-5d6e7f8a9b0c"
}

HTTP statuses

Status	Meaning
200	Done, the answer is in the body
201	Created
204	Done, no body
400	Invalid body or parameters
401	No token, or it is wrong, revoked or expired
402	Not enough money on the balance
403	Not allowed for this token: scope, project, IP or spending limit
404	No such project, service or object
409	State conflict: the server is off, the node is full, the request is still running
413	The file is over 1 MB or not text
429	Too many requests, wait `Retry-After` seconds
503	The panel or node didn't answer — retry later

Error codes

Code	Status	What to do
`token_invalid`	401	The token is wrong, revoked or expired — make a new one
`token_route_forbidden`	403	Not available with a token — do it in the browser
`token_scope_missing`	403	Give the token the scope named in `error`
`token_project_forbidden`	403	The token is limited to other projects or services
`token_ip_forbidden`	403	The request came from an address not on the token's list
`token_spend_limit`	403	The purchase would pass the token's spending limit — raise it
`insufficient_balance`	402	Top up the balance
`idempotency_key_required`	400	Add an `Idempotency-Key` header — see limits and retries
`idempotency_in_progress`	409	A request with this key is still running — wait
`token_rate_limited`	429	Wait `Retry-After` seconds
`server_offline`	409	The server isn't running
`node_full`	409	No room on the node — pick another
`file_not_found`	404	No such file or folder
`file_too_large`	413	Over 1 MB — use SFTP
`path_invalid`	400	Invalid file path
`upstream_unavailable`	503	Retry in a minute; if it persists, write to support with the `requestId`

When an error has no code of its own, code names the status: bad_request, forbidden, not_found, conflict and so on.