You add a maximum-depth rule to a public GraphQL API and real traffic starts failing. How do you set the cap?

## The failure is predictable, so predict it before you ship Adding a maximum-depth validation rule to a public API is a change that looks free and is not. The cap rejects documents at validation, so anything it catches fails completely — no partial data, an `errors` entry and no `data` key — and the clients that break are usually not the ones you were worried about. Two categories break first, and both are avoidable if you know about them. ### Introspection is deeper than product traffic The standard full introspection query is one of the deepest documents any client will ever send. It walks `__schema { types { fields { type { ofType { ofType { … } } } } } }`, and the `ofType` chain is conventionally unrolled several levels to unwrap nested list and non-null wrappers such as `[Animal!]!`. Add the enclosing operation and you are comfortably past ten levels for a query whose execution cost is trivial. So a cap of eight, chosen because no product document goes past six, rejects introspection outright. The symptom is confusing: ordinary reads keep working, but in-browser explorers show an empty docs pane, typed client generators fail their schema fetch, and schema checks in CI go red — all simultaneously, all with a depth error nobody connects to the change. Handle it deliberately: either exempt documents whose root selections are the introspection meta-fields from the depth rule, or set the cap above the introspection query's measured depth. Do not discover this in production. ### Connection conventions spend depth on structure The Relay-style connection convention wraps every list in `edges` and `node`, so one hop costs three levels — the connection field, `edges`, `node` — before you reach a single real field: ```graphql query Descendants { animal(tag: "HFD-4471") { offspring(first: 25) { edges { node { offspring(first: 25) { edges { node { tag } } } } } } } } ``` Two generations of pedigree, one scalar field, already eight levels deep. A four-hop traversal is past fourteen. A cap tuned against a flat schema is simply wrong for a connection-shaped one, and the same is true of any schema whose domain is genuinely recursive — ancestry, org charts, bills of materials, threaded comments. Depth is not a proxy for cost in those schemas; a twelve-generation ancestry walk touches twelve records. ## Set the number from measurement, not from a default The method is the answer an interviewer wants. 1. **Instrument first, enforce later.** Compute the depth of every incoming document and record it as a metric and a log field, but reject nothing. Run that through a full traffic cycle — a weekday peak of around 1,200 requests per minute is a different population from a quiet Sunday — and a full release cycle, so pinned old mobile builds are represented. 2. **Read the distribution, not the mean.** Look at the maximum per client and at the high percentiles, and inspect the deepest documents by hand. Legitimate outliers and abusive outliers look different: one is a known operation from a known client, the other is a chain of the same field. 3. **Set the cap with real headroom above the legitimate maximum.** The purpose is to eliminate the absurd, not to trim the tail. If the deepest genuine document is 14, a cap of 15 is a false- rejection generator and a cap of 25 still refuses everything unbounded. 4. **Enforce in stages, and make the error legible.** Turn it on for unauthenticated traffic before first-party clients; state the limit and the observed value in the error message, because a bare "query too deep" turns every client-side debugging session into a guessing game. 5. **Alarm on rejections.** A sudden rise usually means a new client build, not an attack, and you want to see it before support does. Differentiate clients where you can. First-party callers ship a known, finite set of documents whose depth you can measure exactly at build time, so their cap can be tight. An open endpoint serving arbitrary partner traffic has no such luxury and needs a looser cap backed by other controls. ## Be honest about what the cap is worth A depth limit is a blunt instrument, and a strong candidate says so unprompted. It rejects legitimate deep documents and admits cheap-looking shallow ones; it measures document shape, not work. In this pedigree service the incident that actually hurt was not a deep document at all — it was an `offspring` list on a heavily used sire that grew without a bound over years of records, so a three-level document returned tens of thousands of nodes. No depth cap would have touched it; a page limit on the list argument would have. Treat the cap as a floor that removes the pathological cases cheaply, at validation, before any resolver runs — and pair it with a field-count limit, bounded list pages and a weighted cost model for the cases it cannot see. And say plainly that none of it is specified: the GraphQL specification defines document validity, not resource policy, so every one of these numbers is your house rule.