# 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](/identity/get-a-token). Find the service's endpoint for your region in the
[service catalog](/identity/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:

```sh
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.