# Request and Response Headers

HTTP headers provide metadata about requests and responses. Understanding headers is critical for authentication, caching, and advanced API usage.

## Required Headers

**Authorization**: Authentication credential (required for authenticated endpoints).

```
Authorization: Bearer eyJhbGc...
```

Include the `Bearer` scheme for JWT tokens. For API keys, use:

```
Authorization: Bearer sk_live_abc123
```

**Content-Type**: Specifies request body format (required for POST/PATCH).

```
Content-Type: application/json
```

Always use `application/json`; XML is not supported for request bodies.

## Recommended Headers

**User-Agent**: Identifies your application. Helps with debugging and analytics.

```
User-Agent: MyApp/1.0 (Node.js 18)
```

**Accept**: Specifies desired response format (default: application/json).

```
Accept: application/json
```

**Idempotency-Key**: Ensures idempotent processing for create/update operations.

```
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
```

Use a UUID that's stable across retries. If the same key is used again, the original response is returned.

## Conditional Request Headers

**If-None-Match**: Requests resource only if it differs from the specified ETag.

```
GET /users/user_123
If-None-Match: "etag_abc123"

Response: 304 Not Modified (resource unchanged)
```

Reduces bandwidth for frequently accessed resources.

**If-Modified-Since**: Requests resource only if modified after the specified date.

```
GET /users/user_123
If-Modified-Since: Wed, 18 Feb 2026 12:00:00 GMT

Response: 304 Not Modified
```

## Custom Headers

**X-Request-ID**: Track a specific request through logs and monitoring.

```
X-Request-ID: req_custom_tracking_id
```

If provided, the response includes the same ID for correlation.

**X-Correlation-ID**: Trace related requests across microservices.

```
X-Correlation-ID: corr_abc123
```

Used internally for distributed tracing.

## Rate Limit Headers

All responses include rate limit information:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1645198456
```

Inspect these to avoid hitting limits.

## Response Headers

**Content-Type**: Response body format.

```
Content-Type: application/json; charset=utf-8
```

**Content-Length**: Size of response body in bytes.

```
Content-Length: 2048
```

**Content-Encoding**: Response compression method.

```
Content-Encoding: gzip
```

**Cache-Control**: Caching directives.

```
Cache-Control: public, max-age=300
```

**ETag**: Unique identifier for the resource version (for caching).

```
ETag: "abc123def456"
```

**Last-Modified**: Resource's last modification date.

```
Last-Modified: Wed, 18 Feb 2026 12:00:00 GMT
```

**Location**: URL of newly created resource (for 201 responses).

```
Location: /users/user_456
```

**Retry-After**: How long to wait before retrying (for 429/503 responses).

```
Retry-After: 5
```

## Deprecation Headers

**Deprecation**: Indicates the endpoint is deprecated.

```
Deprecation: true
```

**Sunset**: Date when the endpoint will be removed.

```
Sunset: Sat, 01 Jan 2027 00:00:00 GMT
```

**Link**: Link to migration documentation.

```
Link: <https://docs.example.com/migration>; rel="deprecation"
```

## CORS Headers

**Access-Control-Allow-Origin**: Allowed origins for cross-origin requests.

```
Access-Control-Allow-Origin: https://example.com
```

**Access-Control-Allow-Methods**: Allowed HTTP methods.

```
Access-Control-Allow-Methods: GET, POST, OPTIONS
```

**Access-Control-Allow-Headers**: Allowed custom headers in preflight requests.

```
Access-Control-Allow-Headers: Authorization, Content-Type
```

## Security Headers

**Strict-Transport-Security**: Enforces HTTPS.

```
Strict-Transport-Security: max-age=31536000; includeSubDomains
```

**X-Content-Type-Options**: Prevents MIME type sniffing.

```
X-Content-Type-Options: nosniff
```

**X-Frame-Options**: Prevents clickjacking.

```
X-Frame-Options: DENY
```

## Feature Flag Headers

**X-Feature-Flag**: Enable beta features.

```
X-Feature-Flag: beta.new_analytics_api
```

Features must be explicitly enabled on your account.

## Best Practices

- Include `User-Agent` for debugging support
- Use `Idempotency-Key` for all create/update operations
- Respect `Cache-Control` and `Retry-After` headers
- Log `X-Request-ID` for support tickets
- Monitor deprecation headers for API migrations