Errors

When a request fails, the API returns an HTTP error status and a JSON body that describes the error. This reference lists the format, the codes, and how to handle them.

Error formatCopy Anchor Link

{
  "code": "VALIDATION_FAILED",
  "message": "2 fields failed validation: name, sizeGb",
  "field": "name",
  "details": {
    "errors": [
      { "field": "name", "code": "string_too_short", "message": "String should have at least 1 character" },
      { "field": "sizeGb", "code": "missing", "message": "Field required" }
    ]
  }
}

The API doesn't use 400 Bad Request: a request that doesn't match the operation's schema returns 422 Unprocessable Entity.

Status codes and error codesCopy Anchor Link

Some requests also return 404 Not Found for a feature that the region doesn't offer, for example when you request encryption at rest where the region can't provide it. The message names the feature and the region. Retrying can't change this answer.

Imported projectsCopy Anchor Link

These codes appear only for projects that the platform operator imported for you, with their existing resources:

Validation errorsCopy Anchor Link

A 422 Unprocessable Entity response for an invalid request lists every problem at once in details.errors. Each entry has:

• field: the field's path in the request, with dots between levels, or null when the problem concerns the body as a whole.
• code: the kind of problem, such as missing or string_too_short.
• message: a description in English.

The top-level field describes the first entry, and message names every field. Fix all the listed fields before you send the request again.

Rate limitingCopy Anchor Link

The API gateway limits how fast each credential can send requests. Every API token, service account key, and console session has its own limit, and requests without a credential are limited by source IP address. The limit allows short bursts above the sustained rate.

For an API token or a service account key, the limit applies per credential and also per tenant, over all of the tenant's credentials together. Every response to such a request carries these headers:

When you exceed the limit, the gateway answers 429 Too Many Requests with the code RATE_LIMITED, "retryable": true, and a Retry-After header with the number of seconds to wait, at least 1. Wait at least that long before you send the next request.

This limit applies to requests to the REST API. For the limits of application credentials, see OpenStack API limits.

Errors in asynchronous operationsCopy Anchor Link

When the work of a 202 Accepted request fails, the operation's state becomes FAILED, and its error field contains an error in the format above. An operation that succeeded can carry a warning in the same format, when something that you requested couldn't be delivered. See Synchronous and asynchronous requests.

Responses from the network in front of the APICopy Anchor Link

During a deployment, a proxy in front of the API can answer 500, 502, 503, or 504 with a body that isn't in the error format above, such as plain text. Such a response means that your request didn't reach the API. Retry it with backoff and the same Idempotency-Key.

Retry errorsCopy Anchor Link

• Retry when the response has "retryable": true, and after a 500, 502, 503, or 504 response that isn't in the error format. Send the same Idempotency-Key again. See Idempotent requests.
• Wait longer before each retry, for example 1, 2, 4, and then 8 seconds. After a 429 response, wait at least the Retry-After time.
• Don't retry other 4xx errors unchanged. Fix the request, the credential, or the state of the resource first.

RelatedCopy Anchor Link

• REST API overview
• Authenticate with API tokens
• Idempotent requests