Errors

Hyperstack uses standard HTTP status codes. 2xx means success. 4xx means the request was rejected; fix it and retry. 5xx means a Hyperstack-side issue; retry with backoff.

Error response shape

Every error response uses the same JSON envelope:

jsonError response

{
  "status": false,
  "message": "Insufficient balance to create the resource",
  "error_reason": "bad_request"
}

Field	Type	Description
status	boolean	false on error.
message	string	Human-readable description of what went wrong.
error_reason	string	Machine-readable error category. See the table below.

A small number of responses omit error_reason, most often the legacy 5xx shape ({"message": "Internal Server Error"}) and some pre-validation 400 responses. Treat the missing-key case as bad_request.

Status codes

Code	error_reason	When it occurs	Fix
400	bad_request	Request body or parameters failed validation.	Check the request against the endpoint spec.
400	compatibility_blocked	The selected image and flavor are not compatible. Either the image is restricted to specific flavors, or the flavor is restricted to specific images.	Choose a supported combination using the suggested_flavors or suggested_images array returned in the response. See Image and flavor compatibility.
401	unauthorized	API key missing, malformed, or revoked.	Generate a new API key and pass it as the api_key header. See Authentication.
403	forbidden	The API refused the action for this API key. For example, you already have the maximum of 10 API keys, or the endpoint is only available in the console.	Read the message field, which states the reason.
404	not_found	The resource doesn't exist or was deleted, or the request path is wrong. Some billing history endpoints also return 404 when no data is found for the requested period.	Verify the ID with the corresponding List endpoint, and check the path against the API reference.
405	not_allowed	HTTP method not supported on this path. Also returned when you delete an environment that still contains resources.	Check the spec for the correct method. For an environment, delete the resources listed in the message field first.
406	(none)	A query parameter value isn't acceptable.	Check the parameter's allowed values in the spec.
409	already_exist	A resource with the same identifying attribute already exists.	Use a unique name, or delete the existing resource first.
429	(none)	More than 500 requests per minute from one source IP address.	Retry with exponential backoff. See Rate Limits.
500	server_error	Hyperstack-side issue.	Retry with backoff. If it persists, contact [email protected].