The Gateway as Policy Boundary

Some contract clauses are identical for every endpoint, and enforcing them per-service means N implementations, N configurations, and N chances to drift. The gateway is where those clauses consolidate: authentication verification (validate the token's signature and expiry once, pass verified identity downstream as trusted headers or context — the mechanics live in the security domain; the gateway is where the contract's "requests must be authenticated" clause physically runs), rate limits and quotas as documented behavior — the 429s, Retry-After and limit headers of The Rate-Limit Contract — since only the edge sees a consumer's traffic across all services, request size caps rejecting oversized bodies with 413 before they reach anyone's memory (see Large Requests and Documented Limits), request-ID minting (see Request IDs: The Contract's Correlation Clause), TLS termination, edge Compression: Cheaper Bytes, Not Fewer, CORS, and uniform access logging and metrics — the one vantage point that sees what consumers actually experience (see API Metrics: Rate, Errors, Duration, Sizes).

The test for edge placement is: *does enforcing this clause require any domain knowledge?* Verifying a signature, counting requests per key, measuring a body in bytes and stamping an ID need none. The moment a decision needs to know what a "project" is or who may modify one, it has left gateway territory.

From the consumer's side there is no gateway — there is one API. The 429 your rate limiter emits, the 413 from the size cap, the 401 from token verification, and the 502/504 when an upstream dies are all responses *your contract* produced, and consumers will write branching and retry logic against them. The default failure is a gateway speaking its vendor's dialect: an HTML error page or {"message": "Limit Exceeded"} from the gateway while services emit your documented envelope — so every consumer needs two error parsers, and the one for the edge cases is the one they never tested (see The Error Model: Structure Over Apology).

The fix is to configure the gateway to speak the contract: the same error envelope (machine-readable code, human message, request_id), the promised headers (Retry-After and limit state on 429s — see Retryability: Telling Clients What To Do Next), and documentation that owns the edge responses explicitly: every endpoint can also return 401, 413, 429, 502, 504, with these shapes and these retry semantics. Timeout policy needs the same single-owner treatment: the gateway's upstream timeout must exceed any service's intended processing window, or long requests are killed at the edge into 504s while the service finishes work nobody will receive — the misalignment behind many "Retries and Timeouts as Contract Guidance" incidents, and an argument for Long-Running Operations: 202 and the Job Resource never hiding behind a synchronous edge.

The gateway's convenience is its hazard. Because the edge touches every request and deploys as configuration, it attracts logic that is faster to add there than to route through a service team's backlog: a header-based feature flag, a response rewrite for one client, a retry rule for one flaky upstream. Each is one YAML stanza; together they become a shadow service — unversioned, thinly tested, owned by a platform team that does not know the domain, invisible to service-owning teams debugging behavior their code does not produce. The architecture domain covers the pattern at scale (API Gateway); the contract-level rule is simpler: the gateway *enforces* clauses, it does not *invent* behavior. Anything a consumer would call semantics belongs in a service.

The second failure is drift between layers. The gateway advertises /v2/... routes that no longer match the service's actual paths; the size cap is 1MB at the edge and 10MB in service validation (so the documented 10MB limit 413s at 1MB); authn is enforced at the gateway, and an internal caller bypassing the gateway reaches the service unauthenticated — the edge check must be a *first* line, with service-level verification behind it, or your security boundary is a routing rule (Defense in Depth is the principle). Drift prevention is mechanical, not aspirational: derive gateway config from the same OpenAPI: Describing the Contract, Not Designing It source of truth the services build against, test the edge policies in CI like any other contract surface (see Testing the Contract, Not Just the Code), and give every policy an owner of record (see API Ownership and the Catalog).

And plan for the gateway's own operational weight: it is a hop on every request (typically single-digit milliseconds — cheap, not free), a fleet to scale, and a blast radius of *everything* when its config deploy goes wrong. A staged rollout discipline for gateway config equals its blast radius, which is total.