Reseller API
Errors
Every error code, HTTP status and client recovery action.
Error envelope
Example
{ "error": { "code": "cap_exceeded", "message": "This VM would exceed the reseller account limits." } }
Error codes
| Code | HTTP | Meaning and client action |
|---|---|---|
| internal_error | 500 | Unexpected failure: verify state before retrying; contact support. |
| api_key_required | 401 | Supply rk_ bearer. |
| invalid_api_key | 401 | Replace invalid/revoked key. |
| ip_not_allowed | 403 | Check egress IP/allowlist. |
| key_revoked | 409 | Key revoked during work; replace. |
| insufficient_scope | 403 | Create key with required scope. |
| not_a_reseller | 403 | Account disabled/not reseller; contact operator. |
| reseller_not_configured | 503 | Missing provider/catalog setup; contact operator. |
| invalid_request | 400 | Correct JSON/values/unknown fields. |
| disk_shrink_not_allowed | 400 | Keep/increase disk. |
| invalid_location | 400 | Refresh granted locations. |
| not_found | 404 | Unknown/foreign resource; verify ID. |
| cap_exceeded | 409 | Free capacity/request higher caps; also webhook count. |
| invalid_state | 409 | Refresh VM state. |
| vm_busy | 409 | Wait Retry-After: 30, recheck. |
| not_available | 404 | Password absent/consumed/expired/SSH login; use stored credential or reset. |
| feature_not_available | 409 | Feature disabled/unsupported; inspect account features. |
| resize_partial | 409 | Partial resize: inspect vm/changed, reconcile before repeating. |
| resize_pending | 409 | Resize unconfirmed: poll/wait for reconciliation. |
| provider_error | 502 | Provider failure: back off reads, verify mutations before repeating. |
| rate_limited | 429 | Honor Retry-After, back off. |
Lifecycle errors
| HTTP | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed resize, out-of-range sizes, or no resource change |
| 400 | disk_shrink_not_allowed | Requested disk smaller than current disk |
| 404 | not_found | VM does not exist in the caller's account |
| 409 | cap_exceeded | Resize would exceed an account cap |
| 409 | invalid_state | VM is unavailable for the operation or needs reconciliation |
| 409 | vm_busy | Provider rejected an operation with 423; retry later |
| 502 | provider_error | Provider rejected resize or rescue; no provider payload exposed |
All routes retain standard authentication, scope and rate-limit errors. Stats
provider failures return HTTP 200 with nullable metrics, not provider_error.