Handle errors and rate limits

The Compute API uses standard HTTP status codes and a consistent JSON error envelope.

Error response format

Errors use this structure:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Not found.",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Field	What it means
`error.code`	Stable machine-readable error code. Use this in client logic.
`error.message`	Human-readable explanation. Don’t branch on this text.
`error.request_id`	Identifies the request in Hivenet logs. Include it when contacting Support.

Client logic should branch on error.code, never on error.message. Messages can change without changing the underlying error condition.

Common error codes

Status	Code	Meaning
`400 Bad Request`	`VALIDATION_ERROR`	A parameter or request value is invalid.
`401 Unauthorized`	`UNAUTHORIZED`	The API key is missing or invalid.
`403 Forbidden`	`FORBIDDEN`	The resource exists but the account cannot access it.
`404 Not Found`	`NOT_FOUND`	The requested resource does not exist.
`409 Conflict`	`CONFLICT`	The action can’t proceed in the current state, or a start request has insufficient credit.
`429 Too Many Requests`	`TOO_MANY_REQUESTS`	The rate limit was exceeded.
`500 Internal Server Error`	`INTERNAL_ERROR`	The server could not complete the request.
`503 Service Unavailable`	`INTERNAL_ERROR`	No host currently has enough capacity for the requested start operation.

Handle 409 conflicts

409 Conflict uses error code CONFLICT, but it can have more than one cause.

Start: the instance is terminating or terminated, or the account does not have enough credit.
Stop: the instance is terminating or terminated.
Terminate: the instance is already terminated.

The error message does not distinguish these cases. Fetch the current instance state first. If a start request conflicts even though the instance can be started, check the account balance before retrying.

Fetch the current state

Call GET /instances/{id}.

Check what blocked the action

Use the instance state to identify lifecycle conflicts. For start requests, also check whether the account has enough credit.

Retry only when the cause is resolved

Wait for a valid state transition or add credit as needed before sending the action again.

Handle rate limits

Rate limits apply per source IP address rather than per API key. Clients that share an egress IP also share the same request budget. A 429 Too Many Requests response includes a Retry-After header. Wait that many seconds before retrying.

Retry-After: 60

Don’t pace requests against an assumed fixed limit. Treat the rate limit as subject to change and respond to 429 dynamically.

Handle server errors

A 500 response uses the generic message:

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred.",
    "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

The message is intentionally generic. Use error.code for program logic and keep request_id for troubleshooting. For temporary server errors, retry after a short delay. If the problem continues, contact Support with the request_id.

Handle temporary capacity errors

A start request can return 503 Service Unavailable when no host currently has enough free capacity for the instance’s preset. The body uses INTERNAL_ERROR rather than a separate capacity error code. Retry with backoff, or choose a compatible preset in another region. This is a temporary capacity condition rather than a problem with the request itself.

Retry safely

Request type	Retry guidance
Read-only requests	Usually safe to retry after a short delay.
`400`	Fix the request before retrying.
`401` or `403`	Fix authentication or access before retrying.
`409`	Check the latest instance state and, for start requests, the account balance before retrying.
`429`	Wait for `Retry-After`.
`500`	Retry after a delay; contact Support if it persists.
`503`	Retry with backoff or choose a preset in another region.

Before retrying a destructive action such as terminate, fetch the instance state and confirm the action is still needed.

What to include when asking for help

Include:

The endpoint and HTTP method
The HTTP status
error.code
error.request_id
A redacted request if useful

Never include your API key.

Next step

Continue with API changelog to track API changes.

Public API

API reference

Handle errors and rate limits

Error response format

Common error codes

Handle 409 conflicts

Handle rate limits

Handle server errors

Handle temporary capacity errors

Retry safely

What to include when asking for help

Next step

​Error response format

​Common error codes

​Handle 409 conflicts

​Handle rate limits

​Handle server errors

​Handle temporary capacity errors

​Retry safely

​What to include when asking for help

​Next step

Error response format

Common error codes

Handle 409 conflicts

Handle rate limits

Handle server errors

Handle temporary capacity errors

Retry safely

What to include when asking for help

Next step