# Common headers

Use authentication, tracing, idempotency, and content-type headers consistently.

Product: PNSL API
Guides follow API reference 2.0.0 and event reference 1.0.0.
Canonical page: https://docs.axiym.io/pnsl-api/integration-guide/fundamentals/common-headers

The API Reference is the source of truth for which headers apply to each
endpoint. Header names are case-insensitive; examples use canonical casing.

## Request headers

| Header            | Required                         | Use                                                           |
| ----------------- | -------------------------------- | ------------------------------------------------------------- |
| `Authorization`   | Protected endpoints              | Bearer token from `POST /oauth/token`.                        |
| `X-Request-Id`    | Optional                         | Client-generated request ID for tracing. UUID is recommended. |
| `Idempotency-Key` | Where shown in the API Reference | Safely retry a state-changing operation.                      |
| `Content-Type`    | Requests with a body             | `application/json`, except the form-encoded token request.    |

## State-changing request

```http
POST /{resource} HTTP/1.1
Authorization: Bearer <access_token>
X-Request-Id: 4df45565-62bd-4ceb-9f5e-788a8b501093
Idempotency-Key: operation-2026-001
Content-Type: application/json
```

Use a new `X-Request-Id` for each HTTP attempt, including retries. Axiym echoes
it in the response and records it for support investigation.

Reuse the same `Idempotency-Key` when retrying the same state-changing request
after a timeout, network failure, or ambiguous response.

## Response headers

| Header                  | Use                                                        |
| ----------------------- | ---------------------------------------------------------- |
| `X-Request-Id`          | Request identifier to include in support requests.         |
| `x-ratelimit-limit`     | Maximum capacity in the current rate-limit window.         |
| `x-ratelimit-remaining` | Capacity remaining in the current window.                  |
| `x-ratelimit-after`     | Seconds until capacity becomes available after throttling. |
| `Retry-After`           | Delay before retrying after `429 Too Many Requests`.       |