Rate limits and errors

How the API answers when something is wrong, every error code it can return, and the rate limits that apply to your keys.

Response basics

Every answer, success or error, carries these headers:

No answer sets a cookie. HEAD works on every GET endpoint and returns the same status and headers without a body.

The cacheable reads (/account, /offers, /offers/{id}, /servers, /servers/{id}, /servers/{id}/traffic, /orders, /orders/{id}, /invoices, /invoices/{id}, /ssh-keys) also carry X-Cache: hit or X-Cache: miss. A hit is served from a copy at most about a minute old; the body is the same as a miss.

The error body

{
  "error": {
    "code": "price_changed",
    "message": "The total is not the expected_total that was sent. Nothing was ordered. The current total is in the details.",
    "request_id": "01JCX7Q2M8ZK4T6V9B3N5R1W2Y",
    "details": { "total": { "amount": "13900", "currency": "USD" } }
  }
}

• code is stable. Write your code against it.
• message is fixed text for the code. It never repeats anything you sent.
• details appears only when there is something you can act on. Its keys are listed below.
• 401 answers also carry the header WWW-Authenticate: Bearer. 405 answers carry Allow, the methods the path takes. 429 rate_limited carries Retry-After, and so does any error whose details hold retry_after (in_progress, cooling_off).

Rate limits

There is also a short burst limit per IP address in front of the API.

Successful answers carry the tighter of the key and account counters:

Over a limit the answer is 429 rate_limited with a Retry-After header in seconds. Wait that long, then go on.

The window slides: what counts is roughly the last 60 seconds, so there is no burst at the turn of the minute. X-RateLimit-Reset is the end of the current clock minute.

Writes have their own ceilings (power actions per hour, reverse DNS requests per day, SSH key changes per day, order limits). Those answer 429 action_limit or 403 cap_reached, described on their pages.

Error codes

A 404 looks exactly the same whether the item does not exist or belongs to another account.

Details keys

With details.reason, the invalid_body message names the problem too: The request body is not valid: action: one of on, off, reboot.

Requests the API refuses before it looks at them

• Query parameters exist only where an endpoint lists them (cursor and limit on lists, dry_run=true on orders). Anything else is 400 invalid_parameter.
• GET, HEAD and DELETE must not have a body: 400 body_not_allowed.
• POST bodies are one JSON object, Content-Type: application/json, at most 4 KB. Unknown fields and names given twice are refused: 400 invalid_body. A body over 16 KB is 413 body_too_large.
• Ids in paths must have the right prefix for the endpoint (srv_ on /servers/{id}). A wrong prefix, a leading zero or anything encoded is 404 not_found.