Headers

• Required: Yes. Every request must send an Accept header that includes one of the accepted media types listed below (or a matching wildcard).
• When it is enforced: By a global plugin before any route runs. If the header is missing or does not include an accepted type, the server responds with 406 Not Acceptable and a standard error body.
• Accepted values: One of application/json, application/x-ndjson, application/geo+json, or application/x-ndgeo+json. Wildcards (*/*, application/*) are also accepted. The chosen type selects the response representation — see Response Formats for the differences (including the two streaming formats).
• Examples: Accept: application/json, Accept: application/x-ndjson, Accept: application/json, */*, Accept: text/plain, application/geo+json.

Example 406 response when Accept is missing or invalid:

HTTP/1.1 406 Not Acceptable
content-type: application/json
x-correlation-id: 9c8b88b1-0f4f-4c6d-9c4e-5a7f65e8b123

{
  "meta": {},
  "links": {},
  "data": {
    "error": "Accept header must include one of application/json, application/x-ndjson, application/geo+json, application/x-ndgeo+json",
    "code": "NOT_ACCEPTABLE",
    "tracking_id": "9c8b88b1-0f4f-4c6d-9c4e-5a7f65e8b123"
  }
}

• Request: Optional. Clients can send x-correlation-id to supply their own correlation id. If present and valid, the server uses it as the request id and echoes it in the response and in error bodies as tracking_id. Valid = only letters (a–z, A–Z), digits (0–9), and underscore (_). If absent or invalid, the server generates a UUID.
• Response: On every response, for both success and error cases. Same header name x-correlation-id.
• Format: A UUID string by default, or the value of the request header x-correlation-id if sent.
• How it is used:
  • Included in all error bodies as tracking_id (same value).
  • Sent as the x-correlation-id response header on every response.
  • Can be logged by clients to correlate client-side logs with server-side logs.

Example response (401 error):

HTTP/1.1 401 Unauthorized
content-type: application/json
x-correlation-id: 9c8b88b1-0f4f-4c6d-9c4e-5a7f65e8b123

{
  "meta": {},
  "links": {},
  "data": {
    "error": "Missing API key",
    "code": "MISSING_API_KEY",
    "tracking_id": "9c8b88b1-0f4f-4c6d-9c4e-5a7f65e8b123"
  }
}

Clients should record the x-correlation-id value whenever they handle an error so it can be provided in support tickets or log searches.

---

• Always present: Returned on every response, both success and error.
• Value: Either a server-generated UUID or the value of the incoming request header x-correlation-id (when provided and valid).
• Relationship to tracking_id: The tracking_id field in error bodies is always the same value as the x-correlation-id response header.
• Usage: Clients should log this header for every call and surface it in dashboards and support logs so requests can be correlated with server-side logs.

When the global rate limiting plugin is enabled, responses from rate-limited routes include standard rate-limit headers:

• x-ratelimit-limit: The maximum number of requests allowed in the current window.
• x-ratelimit-remaining: How many requests remain in the current window before the limit is reached.
• x-ratelimit-reset: Unix timestamp (seconds) when the current window resets.

If a client exceeds the configured limit, the server responds with HTTP 429 Too Many Requests and may also include:

• retry-after: Number of seconds the client should wait before retrying.

Clients should:

• Inspect x-ratelimit-remaining to implement backoff before hitting 0.
• Use x-ratelimit-reset or retry-after to schedule retries when they receive a 429.
• Log these headers alongside x-correlation-id for debugging burst/limit issues.