> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hashrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Developer Rules

> This page covers the required headers, idempotency rules, and common error responses that apply to every API request.

## Common headers

All authenticated endpoints require these headers.

| Header              | Required  | Description                                         |
| ------------------- | --------- | --------------------------------------------------- |
| `Authorization`     | Always    | `Bearer <access_token>` from `/v1/auth/token/issue` |
| `Content-Type`      | POST only | `application/json`                                  |
| `X-Idempotency-Key` | POST only | UUID v4 used to prevent duplicate operations        |

**Example**

```
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Content-Type: application/json
X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

## Idempotency

All POST requests must include an `X-Idempotency-Key` header with a valid **UUID v4**.
This ensures retrying a request (for example, after a network timeout) does not create duplicate resources.

**Behavior**

* First request with a given key → processed normally
* Subsequent requests with the **same key** → the original response is replayed without re-executing the operation
* Keys are scoped per client and expire after **24 hours**
* Only successful responses (`2xx`) are cached
* Failed requests can be retried with the same key

**Replay header**

When a request is replayed, the response will include the following header so you can tell it apart from a fresh response:

```
X-Idempotency-Replayed: true
```

**Errors**

If the idempotency key is missing or invalid, the API will reject the request with one of the following errors:

* `400 MISSING_IDEMPOTENCY_KEY` — `X-Idempotency-Key` is required for POST requests
* `400 INVALID_IDEMPOTENCY_KEY` — `X-Idempotency-Key` must be a valid UUID

***

## Common error responses

All error responses follow this format:

```json theme={null}
{
  "success": false,
  "message": "Error description"
}
```

**Authentication errors**

These apply to all authenticated endpoints:

* `401 EMPTY_AUTH_KEY` — Authentication token is required
* `403 INVALID_AUTH_TOKEN` — Authentication token is invalid or expired