Diagnosing 422 Validation Failures in FastAPI Async Endpoints

Recognizable Condition

You send a request to an async FastAPI endpoint, expect a 200 or 201 response, and instead receive a 422 Unprocessable Entity. The response body contains a JSON array under a detail key, naming specific fields and error types. Alternatively, a dependency declared with Depends() fails to inject the expected object, causing either a 500 Internal Server Error or an unexpected None inside your endpoint. In both cases, FastAPI rejects or mishandles the request before your endpoint logic runs.

Cause and Diagnostic Table

Symptom	Likely Cause	Diagnostic Signal
422 with "type": "missing"	Required Pydantic field absent from payload	detail entry names the missing field
422 with "type": "int_parsing" or similar	Client sent wrong data type	detail entry shows received value and expected type
500 from dependency callable	Depends() target has incompatible signature	Traceback points to dependency, not endpoint
Endpoint receives None for session	Dependency returned None or was skipped	Debug log or type check inside endpoint fails
422 on form submission	Content-Type mismatch (JSON vs form)	Request headers show application/json but endpoint expects form data

Ordered Checks

Run these checks in order. All commands assume you have curl and jq available and network access to the FastAPI service. No special filesystem permissions are required unless you are reading server logs.

1. Inspect the generated OpenAPI schema. FastAPI builds /openapi.json automatically from your path operations and Pydantic models. Confirm the expected request body shape.

   curl -s http://localhost:8000/openapi.json | jq '.paths["/your-path/"]["post"].requestBody'

   Replace /your-path/ and post with your actual route and method. Expected check: the schema lists the same fields and types your client sends. Risk: read-only; none.
2. Reproduce the 422 with a minimal payload. Send the smallest valid request you can construct and capture the error detail.

   curl -i -X POST http://localhost:8000/your-path/ \
     -H "Content-Type: application/json" \
     -d '{"field_name":"value"}'

   Replace field_name with a required field from the OpenAPI schema. Expected check: if you still receive 422, the detail array identifies the exact field and error type. Risk: none.
3. Verify the request Content-Type. FastAPI decides how to parse the body based on this header. A JSON payload sent with the wrong header will fail validation.

   curl -v -X POST http://localhost:8000/your-path/ \
     -H "Content-Type: application/json" \
     -d '{"field_name":"value"}' 2>&1 | grep -i "content-type"

   Expected check: the outgoing header matches what the endpoint expects (application/json, application/x-www-form-urlencoded, or multipart/form-data). Risk: none.
4. Audit dependency signatures. Review every callable passed to Depends(). FastAPI inspects type hints to decide what to inject. Expected check: parameters are either sub-dependencies, FastAPI-recognized types (Request, Response, BackgroundTasks, SecurityScopes), or Pydantic models for query/body data. Risk: none.
5. Check Pydantic model version. FastAPI supports both Pydantic v1 and v2, but validator syntax and error formats differ. Expected check: your models and custom validators match the major version installed in your environment. You can confirm the version in your dependency file or by running pip show pydantic in your project's virtual environment. Risk: none.

Fixes Tied to Findings

• OpenAPI schema shows a required field your client omits. Either add the field to the client payload or give the Pydantic field a default value (e.g., name: str = "default") so it becomes optional.
• 422 detail reports a type mismatch. Correct the client payload, or adjust the Pydantic field type if the API contract should accept the incoming value. For example, change price: float to price: Union[float, str] only if you intend to handle strings.
• Content-Type mismatch. Set the correct header on the client request. If the endpoint expects form data, use Form() parameters in the signature instead of a Pydantic body model.
• Dependency signature is incompatible. Remove unrecognized parameters, wrap them in their own Depends(), or declare them as FastAPI built-in types. For example, a database session should come from a sub-dependency that yields the session, not from a plain type hint.
• Pydantic version mismatch. Align custom validators with the installed major version. In Pydantic v2, use @field_validator; in v1, use @validator.

Escalation Criteria

Escalate to a framework-level investigation or senior review when:

• The OpenAPI schema at /openapi.json does not reflect recent code changes, suggesting a caching or import error.
• A 422 persists after the payload, Content-Type, and Pydantic model are confirmed correct.
• A dependency raises a 500 error with a traceback that does not point to your application code.
• BackgroundTasks parameters are declared but never execute after a successful response.
• Multiple endpoints fail validation in the same way, indicating a shared base model or middleware issue rather than a single route.

Before escalating, capture the exact curl command, the full 422 response body, the relevant route signature, and the output of pip show fastapi pydantic from your environment. This gives the next engineer enough context to reproduce the issue without guessing.