In a service built on a web framework, one endpoint's payload is shaped unlike every other — how do you diagnose it?

## Start from the bytes, not from the model The first mistake in this investigation is reasoning about what the model *should* produce. Capture what the endpoint actually returns and compare it with a healthy endpoint from the same service: - key casing and spelling; - the form of timestamps, including precision and offset; - whether null members are present or omitted; - the representation of enumerated values; - any wrapper or envelope around the payload; - the response's content type header. An unexpected content type is the single strongest clue available, because it usually means a different writer was selected entirely rather than the same writer behaving differently. ## Establish whether the body passed through the registered serializer at all This is the branch that splits the whole diagnosis in two, and it is cheap to settle. Add a distinctive, temporary policy to the shared configuration — flip null omission, or register a converter that marks one known type — and re-request both endpoints. If the control endpoint changes and the suspect endpoint does not, the suspect body never reached the shared instance. Instrumenting the registered writer to record which route it served answers the same question without changing behaviour. A second, zero-cost signal: compare the endpoint's **error** body with its success body. Framework-generated bodies go through the registered instance, so an endpoint whose validation-failure body matches the house conventions while its success body does not has a bypass on the success path specifically. ## The escape routes are a finite list | Escape route | Characteristic symptom | Fix | |---|---|---| | Handler constructs its own serializer | success body drifts, error body does not | delete it; use the registered instance | | Body assembled as text and written directly | spacing, ordering or escaping artifacts no configured serializer would produce | return the model, not a string | | A component returns an already-encoded payload | the body appears as a quoted, escaped string, or the payload is double-encoded | hand over the structured value, or declare the payload pre-encoded | | Per-type or per-property overrides on the model | only some fields differ, and they differ identically wherever the model is embedded | remove the override or make it the convention | | A second registered instance selected by media type or route scope | the whole endpoint differs, error bodies included | collapse to one instance, or justify the second | | A filter or proxy rewriting bodies in flight | what the handler wrote and what the client received differ | inspect at the process boundary | Working down that list in order is faster than reading the handler, because each row has a distinguishing symptom you can check from outside the process. ## Fix the cause, then fence it 1. Remove the bypass. If the divergent shape was actually intended, express it deliberately — as a per-endpoint option on the model, or as a second instance configured beside the first with a comment saying which consumer it serves. 2. Add a test that drives every endpoint and compares against stored documents, so the next drift fails the build instead of an integration. 3. Add a rule forbidding serializer construction outside the configuration module. This is the control that actually holds, because it removes the easy wrong path rather than relying on reviewers to spot it. ## Two traps inside the diagnosis itself - **Reproducing through a client library.** If you inspect the payload through a generated client or a console that pretty-prints, you are looking at that tool's rendering, not the bytes. Capture the raw response. - **Changing two things at once.** The temporary probe described above is only decisive if it is the single change in flight. Apply it, observe both endpoints, then remove it before touching anything else. ## Why this keeps happening A serializer is trivially constructible, and the correct path — reaching the instance the framework already holds — is the less obvious one. The local instance works in the handler's own unit test, produces plausible output by hand inspection, and diverges only in details nobody compares until a client integrates against two endpoints at once. That is why the durable answer to this question is not the diagnosis but the fence you leave behind.