Skip to main content
INTG-STD-016v1.0.0DRAFTINTEGRATIONstandard

HTTP Header Standards

Purpose​

HTTP headers carry essential metadata — correlation identifiers, content negotiation, caching directives, security controls, and rate-limit signals — yet no existing integration standard governs them holistically. This standard unifies header requirements that are currently scattered across INTG-STD-009 (error handling), INTG-STD-029 (observability), and INTG-STD-015 (events) into a single, enforceable specification. Without it, teams independently invent header conventions, causing interoperability failures at gateways, inconsistent observability, and security gaps.

Normative language (MUST, SHOULD, MAY) follows RFC 2119 semantics.

Rules​

R-1: Required Standard Headers​

Every HTTP API response MUST include the following headers:

HeaderValueRequirement
Content-TypeMedia type of the response bodyMUST be present on all responses with a body
X-Correlation-IDUUID v4 — end-to-end correlationMUST be present on all responses
X-Request-IDUUID v4 — per-hop request identifierSHOULD be present; MUST be unique per request

Every HTTP API request carrying a body MUST include the Content-Type header.

R-2: Correlation and Tracing Headers​

  • If the inbound request includes X-Correlation-ID, the server MUST propagate it unchanged in the response and to all downstream calls.
  • If the inbound request does not include X-Correlation-ID, the server MUST generate a new UUID v4 and include it in the response.
  • The X-Correlation-ID response header MUST match the correlationId field in RFC 9457 error response bodies (per INTG-STD-009 R-7).
  • Servers SHOULD propagate W3C traceparent and tracestate headers per INTG-STD-029 for distributed tracing.
  • X-Request-ID MUST NOT be reused across retries; each attempt is a distinct request.

R-3: Content Negotiation​

  • Clients SHOULD include the Accept header to indicate preferred response media types.
  • Servers MUST respect Accept when multiple representations are available and MUST return 406 Not Acceptable when the requested type cannot be served.
  • Content-Type MUST include the charset parameter when the media type does not imply UTF-8. For application/json, the charset parameter is OPTIONAL (RFC 8259 mandates UTF-8).
  • Servers SHOULD include Content-Language when serving localised content.

R-4: Custom Header Naming​

  • Custom headers MUST NOT use the X- prefix for new headers (per RFC 6648, which deprecates the convention for newly defined headers).
  • The only exception is X-Correlation-ID and X-Request-ID, which are retained for backward compatibility and widespread ecosystem adoption.
  • Organisation-specific custom headers SHOULD use a short organisational namespace prefix (e.g., Acme-Tenant-ID, Precepts-Trace-Source).
  • Custom header names MUST use Title-Case-With-Hyphens (HTTP/1.1 convention) and MUST NOT use underscores.
  • Custom headers MUST be documented in the API specification (OpenAPI headers object or equivalent).

R-5: Caching Headers​

  • Servers MUST include Cache-Control on cacheable responses.
  • Servers SHOULD include ETag or Last-Modified on resource representations to support conditional requests.
  • Cache-Control: no-store MUST be set on responses containing sensitive or user-specific data.
  • Clients SHOULD send If-None-Match or If-Modified-Since for conditional GET requests.

R-6: Rate-Limit Headers​

Rate-limited endpoints MUST communicate limits using the following headers:

HeaderDescriptionRequirement
RateLimit-PolicyQuota definition (e.g., 100;w=60)SHOULD be present on all responses from rate-limited endpoints
RateLimitRemaining quota and reset windowSHOULD be present on all responses from rate-limited endpoints
Retry-AfterSeconds or HTTP-date to wait before retryingMUST be present on 429 responses; SHOULD be present on 503 responses
  • Retry-After MUST use seconds (integer) format for programmatic consumption. HTTP-date format MAY be used additionally.
  • Rate-limit header values MUST NOT leak internal infrastructure details (e.g., node-specific counters).

R-7: Authentication Headers​

  • Authentication credentials MUST be transmitted in the Authorization header using a registered scheme (e.g., Bearer, Basic).
  • Credentials MUST NOT be transmitted in query strings, custom headers, or cookies for API-to-API communication.
  • The Authorization header MUST carry short-lived tokens (OAuth 2.0 access tokens per SEC-STD-001); API keys MAY be used only for legacy system identification and MUST NOT be the sole authentication mechanism for new integrations.
  • The WWW-Authenticate header MUST be present on 401 responses, indicating the required authentication scheme.

R-8: Security Response Headers​

API responses SHOULD include the following security headers where applicable:

HeaderValueApplicability
Strict-Transport-Securitymax-age=31536000; includeSubDomainsMUST on all HTTPS endpoints (per SEC-STD-003)
X-Content-Type-OptionsnosniffSHOULD on all responses
X-Frame-OptionsDENYSHOULD on API responses not intended for iframe embedding
  • API responses MUST NOT include Server headers that reveal software name or version.
  • API responses MUST NOT include X-Powered-By or similar technology-disclosure headers.

R-9: Header Size Constraints​

  • Total request header size MUST NOT exceed 8 KiB across all headers combined.
  • A single header value SHOULD NOT exceed 4 KiB.
  • Servers MUST return 431 Request Header Fields Too Large when header limits are exceeded.

R-10: Forbidden Headers​

The following headers MUST NOT be used in API integrations:

  • X-Forwarded-For MUST NOT be trusted or acted upon without gateway-level validation and sanitisation.
  • X-Real-IP MUST NOT be used as a substitute for authenticated identity.
  • Custom headers carrying JSON-encoded payloads MUST NOT be used; structured data belongs in the request or response body.

Examples​

Compliant Response Headers​

HTTP/1.1 200 OK
Content-Type: application/json
X-Correlation-ID: 550e8400-e29b-41d4-a716-446655440000
X-Request-ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Cache-Control: private, max-age=300
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
RateLimit-Policy: 100;w=60
RateLimit: limit=100, remaining=87, reset=42
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff

Compliant 429 Response​

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
X-Correlation-ID: 550e8400-e29b-41d4-a716-446655440000
Retry-After: 30
RateLimit-Policy: 100;w=60
RateLimit: limit=100, remaining=0, reset=30

Non-Compliant — Credential in Query String​

GET /v1/orders?api_key=sk_live_abc123 HTTP/1.1

Violation: Credentials in query string (violates R-7). Credentials MUST be in the Authorization header.

Enforcement Rules​

Gateway-Level​

  • API gateways MUST inject X-Correlation-ID if the backend has not provided it.
  • API gateways MUST strip Server and X-Powered-By headers from outbound responses.
  • API gateways SHOULD validate Content-Type presence on request and response bodies.

Build-Time​

  • OpenAPI specifications MUST declare required headers (X-Correlation-ID, Content-Type) on all operations.
  • Linters SHOULD flag custom headers using the deprecated X- prefix for new definitions.
  • Contract tests MUST validate that 429 responses include Retry-After.

References​

Rationale​

Why unify header standards? Header rules are scattered across error handling (R-7 in INTG-STD-009), observability (INTG-STD-029), and event bindings (INTG-STD-015 R-8). A single authoritative document prevents contradictions and gives gateway teams one reference for enforcement configuration.

Why retain X-Correlation-ID despite RFC 6648? RFC 6648 deprecates the X- prefix for new headers, but X-Correlation-ID and X-Request-ID are de-facto standards with near-universal gateway, framework, and observability tooling support. Renaming would fracture the ecosystem for no material benefit.

Why prohibit credentials in query strings? Query strings are logged by proxies, CDNs, and browser history. OWASP and SEC-STD-001 mandate the Authorization header to prevent credential leakage.

Why mandate RateLimit headers? Without proactive rate-limit signals, clients resort to trial-and-error, causing burst overloads. The IETF draft standardises a machine-readable format that clients and gateways can consume programmatically.

Version History​

VersionDateChange
1.0.02026-09-08Initial definition