Make API requests
Authenticate, find endpoints, read errors and retry when you call the APIs directly over HTTPS.
Every service has an HTTP API. The openstack CLI and the OpenStack SDK call
these APIs for you. This page is for calling them directly.
Authenticate and find the endpoint
Every request needs a token from Identity in the X-Auth-Token header. See
Get a token. Find the service's endpoint for your region in the
service catalog. Each service's API reference lists its paths, which
start with a version, such as /v3/ or /v1/.
This request asks Identity which projects you can access:
curl https://auth.vexxhost.net/v3/auth/projects \
--header "X-Auth-Token: $TOKEN"Send and receive JSON
Request and response bodies are JSON. Send Content-Type: application/json with a body. Some
services let you choose a newer version of their API for each request with the
OpenStack-API-Version header. Their API reference says when.
Read errors
The status code shows what went wrong and whether to retry. The body adds detail in a format that varies by service. Each API reference describes its own.
| Status | Meaning | Retry |
|---|---|---|
400 Bad Request | The request cannot be done as written. | No. Fix the request. |
401 Unauthorized | The token is missing or has expired. | After getting a new token. |
403 Forbidden | The token's project or roles do not allow this, or a quota is reached. | No. |
404 Not Found | The resource does not exist, or your project cannot see it. | No. |
409 Conflict | The resource is in a state that does not allow this, or it changed since you read it. | After reading it again. |
413 Content Too Large | The request body is too large. | No. |
422 Unprocessable Entity | The body does not match what the operation expects. | No. Fix the request. |
429 Too Many Requests | The service is busy, or you sent too many requests. | Yes, after Retry-After seconds. |
503 Service Unavailable | The service cannot answer right now. | Yes, with backoff. |
504 Gateway Timeout | The request took too long. | Yes, with backoff. |
Retry safely
Wait as long as Retry-After says when a response includes it. Otherwise retry 503 and 504
with exponential backoff, starting at about one second. Other 4xx responses fail the same way
every time, so fix the request instead of retrying it.
Request IDs
Responses carry a request ID header, such as X-Openstack-Request-Id. Include it when you contact
support about a request, so support can find the request quickly. Each API reference names the header
its service uses.