Compute API error reference

This page documents common error responses from the Compute API (Nova v2.1), explains what they mean operationally, and provides next-step actions. Use this reference when your API call returns an unexpected status code or when an instance enters an error state.

HTTP status codes#

Nova returns the same 401 body whether the token is missing, expired, malformed, or revoked, so the response does not tell you which case you hit. If openstack token issue succeeds and the request still returns 401, the most common remaining cause is a stale environment variable that points to a different project's token.

Example error response#

{
  "forbidden": {
    "code": 403,
    "message": "Quota exceeded for resources: ['instances']. Requested 1, but already used 10 of 10 instances"
  }
}

The Compute API (Nova) returns errors as JSON envelopes, as shown above. Not every Quake AI service does: the Image service (Glance) returns error bodies as HTML. Branch on the HTTP status code rather than parsing the response body. For the Glance status codes, see Image API error responses. For the Instance API action endpoints and their async state transitions, see Instance API response codes.

Server fault interpretation#

When an instance enters the ERROR state, the fault field in the server response contains diagnostic information.

Reading the fault object#

The fault field is not a recognized column for openstack server show, so -c fault fails with No recognized column names in ['fault']. Read the field from JSON output instead:

openstack server show YOUR_INSTANCE -f json | jq .fault

Nova populates fault only when the server is in ERROR status. On ACTIVE, SHUTOFF, and other states the field is null, which is expected. The raw Compute API returns the same data: GET /v2.1/servers/{server_id} includes a top-level fault object when the status is ERROR.

The fault object includes:

• message: description of the failure
• code: HTTP status code associated with the failure
• created: timestamp when the fault occurred

Common fault messages#

State-conflict handling#

Instance lifecycle actions are only valid in certain states. Sending an action to an instance in the wrong state returns HTTP 409 Conflict.

Handling 409 responses#

1. Check current instance status:

openstack server show YOUR_INSTANCE -c status -c task_state

1. Wait for the current operation to complete. The task_state field shows what the instance is doing (e.g., spawning, rebooting, resize_migrating).

2. Once task_state is None and the instance is in a valid state for your action, retry.

Key pair errors#

Key pair operations return specific errors that are commonly misdiagnosed, especially during instance creation.

For SSH connectivity failures after the instance is running (timeouts, permission denied, wrong username), see the instance connectivity runbook.

Quota-related errors#

When the Compute API returns 403 Forbidden with a quota message, the request was valid but your project lacks capacity.

Quota exceeded for resources: ['instances'] (HTTP 403)
Quota exceeded for resources: ['cores', 'ram'] (HTTP 403)

Resolution:

1. Check quota usage: openstack quota show --usage
2. Identify the exhausted resource
3. Clean up unused instances or request a quota increase

Quake AI-specific quota names#

openstack quota show --usage lists quota names beyond the upstream Nova and Cinder catalog. The Compute API returns 403 Forbidden against these limits the same way it does for the standard quotas.

A limit of -1 means unlimited. Read these values with openstack quota show --usage; the GET /v2.1/limits endpoint does not expose the Quake AI-specific quota names.

See the quota and limits troubleshooting page for detailed recovery procedures.

When to escalate#

Escalate to support when:

• An instance is stuck in ERROR state and the fault message does not point to a quota, capacity, or configuration issue you can resolve
• A 500 or 503 error persists after multiple retries with backoff over 5 minutes
• The fault object, read with openstack server show YOUR_INSTANCE -f json | jq .fault, describes a failure you cannot interpret
• Instance behavior contradicts the documented state machine (e.g., an ACTIVE instance that accepts no actions)

Escalation-ready evidence checklist#

When a Compute API error is not self-resolvable, collect this evidence before filing a support ticket:

See also#

• Compute API reference
• Error response format: JSON error structure, fault objects, request correlation
• API rate limits: quotas vs. rate limits, /limits endpoint, 429 handling
• Retry and resilience patterns: backoff, jitter, and which errors to retry
• Instance lifecycle troubleshooting
• Instance connectivity troubleshooting
• Quota and limits troubleshooting