Diagnose rejected requests across HTTP, validation and variables

Understand the likely causes

• Possible causes include a proxy or authentication rejection, wrong Content-Type, malformed JSON, syntactically invalid GraphQL, schema drift, an unselected operation in a multi-operation document or variables that violate declared types. A valid JSON body does not prove that the contained GraphQL document validates against the deployed schema.

Separate transport evidence from language evidence

Start with the client’s existing response metadata and a redacted reproduction record. A proxy HTML page or authentication response is not a GraphQL result even when the URL ends in /graphql. If the body is GraphQL JSON, determine whether execution began: request errors normally prevent a data result, while field errors can accompany data. Error wording is implementation-specific, so use stage and structured metadata rather than a single text substring. Do not log credentials, authorization headers or private variable values while collecting the fixture.

Compare the exact document and schema artifacts

Record the intended server release and the client’s exact composed operation, including fragments. An unknown field can be a misspelling, but it can also indicate that the client deployed before server support or that an old instance remains in a rolling release. Validate the document against the intended local schema artifact using the project’s installed tooling, without probing unrelated endpoints. If the document contains several operations, ensure operationName selects the intended one. A deprecated field remains valid until it is removed; deprecation alone is not the cause of an unknown-field error.

{"query":"query Card($id: ID!) { course(id: $id) { title } }","operationName":"Card","variables":{"id":"c1"}}

Correct the narrow input mismatch

Check variable declaration, argument position and JSON representation together. A variable declared String is not interchangeable with ID! merely because both examples contain text. A required variable cannot be omitted or explicitly null. For optional input, distinguish omission from null and review applicable defaults. Repair the client fixture or the intentionally designed schema contract; do not weaken every argument to an unvalidated string just to silence one error. For HTTP, pair the JSON body with supported content negotiation and reject mutation execution through GET according to the integration contract.

Verify rejection without accidental source effects

Use isolated operation tests with a synthetic service spy to confirm that invalid syntax, unknown fields and invalid required variables cause no resolver write. A corrected positive fixture should return exactly the selected authorized data. Keep transport tests separate for media type, authentication and method rules. The local JSON example here is nonexecuting, and no GraphQL engine or endpoint was contacted. If the actual project has no installed parser, preserve the fixture and limitation instead of installing dependencies or calling a production service merely to obtain an error message.

Keep it from recurring

• Generate client artifacts from a pinned schema, validate complete documents in review and retain representative variable fixtures. Coordinate server/client overlap and rollback. Log safe stage metadata and document identifiers while keeping secrets and user input out of routine logs.