API Error Reference

Error reference for Quake AI APIs. This page covers HTTP status codes common across all services, OpenStack fault response patterns, and service-specific error handling.

Authentication errors (401, 403) are covered in detail on the Authentication page. The Versions & Microversions page explains the 406 Not Acceptable microversion ceiling error.

Common HTTP status codes

400Bad Request

Malformed request body, missing required fields, or invalid parameters

Services: All · Action: Check request syntax against the service API reference

401Unauthorized

Authentication failed: token expired, missing, or invalid

Services: All · Action: Re-issue your token: openstack token issue

403Forbidden

Valid token but insufficient permissions, or quota exceeded

Services: All · Action: Check role assignments and quota usage

404Not Found

Resource does not exist or has been deleted

Services: All · Action: Verify the resource ID with the appropriate list command

409Conflict

Action conflicts with the resource's current state

Services: Compute, Network, Block Storage · Action: Check resource status and resolve the conflict before retrying

412Precondition Failed

Revision mismatch on concurrent modification (If-Match header)

Services: Network · Action: Re-read the resource and retry with the current revision

413Over Limit / Entity Too Large

Quota exceeded or upload exceeds size limit (5 GB for single-part)

Services: All · Action: Check quota with openstack quota show --usage, or use multipart upload

429Too Many Requests

Request rate limited at the gateway layer

Services: All · Action: Back off and retry with exponential backoff. Check Retry-After header if present

500Internal Server Error

Server-side failure

Services: All · Action: Retry after a brief delay. If persistent, escalate to support

503Service Unavailable

Service temporarily overloaded or under maintenance

Services: All · Action: Retry with exponential backoff

OpenStack error response format

All OpenStack APIs return error details in the response body. The exact format varies by service, but most follow this pattern:

{
  "badRequest": {
    "code": 400,
    "message": "Invalid input for field/attribute name. ..."
  }
}

Compute (Nova) uses a fault object on instances in the ERROR state:

{
  "fault": {
    "message": "No valid host was found.",
    "code": 500,
    "created": "2026-04-01T12:00:00Z"
  }
}

The S3-compatible interface returns AWS-standard XML errors:

<Error>
  <Code>InvalidAccessKeyId</Code>
  <Message>The access key does not exist</Message>
  <RequestId>tx00000...</RequestId>
  <Resource>/my-bucket/my-key</Resource>
</Error>

Quota errors (all services)

When any API returns 403 Forbidden with a quota message, the request was valid but your project lacks capacity. Each service enforces quota on different resources.

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

Resolution:

Check quota usage: openstack quota show --usage
Identify the exhausted resource
Clean up unused resources or request a quota increase through the support portal

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

Service-specific error handling

▶

Compute (Nova)

Server faults, state conflicts, and common fault messages

Reading the fault object

When an instance enters the ERROR state, inspect the fault field for diagnostic information:

openstack server show YOUR_INSTANCE -c fault

Common fault messages

Fault message	Meaning	Resolution
`No valid host was found`	Scheduler cannot place the instance on any compute host	Try a smaller flavor. Check quota. If all flavors fail, file a support ticket.
`Volume did not finish being created`	Boot volume (Block Storage) timed out during creation	Check for orphaned volumes. Delete and retry with image-based boot.
`Exceeded maximum number of retries`	Scheduler retried placement and failed repeatedly	Likely a capacity issue. Wait and retry, or try a different flavor.
`PortBindingFailed`	Networking service cannot bind the instance's port	Verify network exists and is accessible. Recreate on a working network.
`block_device_mapping is not valid`	Block device configuration is invalid	Check volume or image reference. Verify the image/volume exists.

State-conflict handling (409 Conflict)

Instance lifecycle actions are only valid in certain states:

Action	Required state	Common conflict
`reboot`	ACTIVE, SHUTOFF, ERROR	Instance in BUILD: wait for build
`start`	SHUTOFF	Instance already ACTIVE
`stop`	ACTIVE	Instance already SHUTOFF or in BUILD
`resize`	ACTIVE, SHUTOFF	Instance in VERIFY_RESIZE: confirm or revert first
`delete`	Any (except DELETED)	Instance in DELETING: already being deleted
`rebuild`	ACTIVE, SHUTOFF, ERROR	Instance in BUILD: wait for build

Check instance status with openstack server show YOUR_INSTANCE -c status -c task_state. Wait for task_state to become None, then retry.

Full compute reference: Compute API →

▶

Network (Neutron)

Port, router, floating IP, and security group conflicts

Port errors

Error	Cause	Resolution
`Port is still in use (409)`	Port attached to instance, router, or floating IP	Check device_owner with openstack port show. Detach the owning resource first.
`PortBindingFailed`	Network not available on the scheduled compute host	Verify network exists. Recreate instance on a different network.
`Traffic dropped despite rules`	Port security anti-spoofing blocks non-matching source IPs	Add allowed address pairs, or disable port security (less secure).

Router errors

Error	Cause	Resolution
`Interface conflict (409)`	Subnet already attached to another router	Remove subnet from the other router, then add to the target router.
`External gateway failure`	External network does not exist or is not accessible	List external networks: openstack network list --external
`Deletion blocked (409)`	Router has active interfaces or a gateway	Remove all interfaces and clear the external gateway before deleting.

Floating IP & security group errors

Error	Cause	Resolution
`FIP association fails (400/404)`	Port doesn't exist, FIP already associated, or no router path	Verify FIP is unassociated and instance network connects to a router.
`Duplicate rule (409)`	Identical security group rule already exists	List existing rules to confirm; no action needed if intent matches.
`Security group in use (409)`	Security group still assigned to ports	Reassign ports to a different group before deleting.

Full network reference: Network API →

▶

Block Storage (Cinder)

Volume state machine, delete conflicts, and snapshot errors

Volume state machine

Volumes follow a strict state machine. Operations are only valid from certain states. Understanding this prevents most 409 errors.

State	Valid operations	Invalid operations (409)
`creating`	(wait)	Attach, detach, delete, extend, snapshot
`available`	Attach, delete, extend, snapshot, backup	Detach (not attached)
`in-use`	Detach, snapshot, extend (if backend supports)	Attach (already attached), delete
`attaching`	(wait)	All operations except status check
`detaching`	(wait)	All operations except status check
`error`	Delete, reset state	Attach, detach, snapshot, extend
`error_deleting`	Reset state	All standard operations

Common delete failures

Error	Cause	Resolution
`Volume is in-use`	Volume attached to an instance	Detach the volume first: openstack server remove volume ...
`Volume has snapshots`	Dependent snapshots exist	Delete all snapshots before deleting the volume.
`Status must be available or error`	Volume in transitional state	Wait for completion, or reset state if stale (>10 min).

Caution: State reset (openstack volume set --state available) bypasses the service's internal tracking. Only use it when you are certain the volume is not actively in use.

Full block storage reference: Block Storage API →

▶

Object Storage (Swift / S3)

S3 authentication errors, credential type confusion, and upload failures

S3-compatible API authentication errors

Error code	HTTP	Resolution
`InvalidAccessKeyId`	403	Verify EC2 credentials exist: openstack ec2 credentials list
`SignatureDoesNotMatch`	403	Check region (us-east-1), endpoint URL, and secret key. Use SigV4.
`AccessDenied`	403	Verify credential project scope matches the container's project.
`RequestTimeTooSkewed`	403	Sync system clock with NTP (max 15 min offset).

Common mistake: The S3-compatible interface requires EC2 credentials, not application credentials. Using application credentials with an S3 client results in InvalidAccessKeyId on every request. Create EC2 credentials with openstack ec2 credentials create.

Upload errors

Error	Cause	Resolution
`EntityTooLarge (400)`	Single-part upload exceeds 5 GB limit	Configure multipart upload (threshold: 64 MB recommended).
`Incomplete multipart upload`	Upload interrupted; parts consume storage	List and abort: aws s3api list-multipart-uploads / abort-multipart-upload
`Timeout during transfer`	Bandwidth/latency exceeds client timeout	Increase chunk size or client timeout. Use rclone for large transfers.

Swift-native API errors

Swift returns standard HTTP status codes. The most common errors are 401 (expired token), 403 (wrong role), 404 (wrong account prefix or missing container), and 413 (segment exceeds 5 GB, so use SLO/DLO for large objects).

Full object storage reference: Object Storage API → · S3-Compatible API →

Escalation-ready evidence checklist

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

Item	How to get it
Resource ID and status	`openstack {resource} show YOUR_ID -c id -c status`
Full error response	`The complete error message, fault object, or XML body`
Request details	`HTTP method, URL, parameters, and timestamp`
Quota usage	`openstack quota show --usage`
Token validity	`openstack token issue (confirms auth is working)`
Console log (Compute)	`openstack console log show YOUR_INSTANCE --lines 50`
Network topology (Network)	`openstack network list && openstack router list`
Credential type (S3)	`openstack ec2 credentials list -c Access`