Errors & rate limits
A consistent error envelope and predictable status codes.
Envelope
Every error response has the same shape:
json{ "error": { "code": "payment_required", "message": "Insufficient credits.", "details": null } }
Status codes
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | Validation failed; see details. |
| 401 | unauthorized | Missing or invalid token. |
| 402 | payment_required | Not enough credits, or server limit reached. |
| 403 | forbidden | Admin-only endpoint, or insufficient key scope. |
| 404 | not_found | No such server/instance, or not yours. |
| 409 | conflict | No node has capacity for the request. |
| 429 | rate_limited | Too many requests. |
| 502 | upstream_error | An upstream panel returned an error. |
| 500 | internal_error | Unexpected server error. |
Rate limits
The API allows 240 requests per minute per client. Exceeding it returns 429. Health checks and the OpenAPI document are exempt. Back off and retry with jitter on a 429.
Validation details
400 responses include a details object from the schema validator listing the offending fields, so you can surface precise messages to users.