Introduction

APIs validate incoming JSON request bodies against a schema to ensure data integrity. When a nested field in the request body fails validation -- due to wrong type, missing required field, or value outside allowed range -- the API returns a 400 Bad Request. The error message may not clearly indicate which nested field caused the failure, making debugging difficult for API consumers.

Symptoms

  • API returns 400 Bad Request with generic validation error message
  • Error message does not clearly identify the failing nested field
  • Request works with simplified payload but fails with full nested structure
  • Validation error points to a parent object but not the specific child field
  • Error message: {"error":"validation_failed","message":"Request body does not match schema"}

Common Causes

  • Nested field type mismatch (string vs integer, object vs array)
  • Required nested field missing from the request
  • Nested field value outside the allowed enum or range
  • Schema updated with new required fields but client not updated
  • JSON path in the validation error truncated or unclear

Step-by-Step Fix

  1. 1.Validate the request body against the schema locally: Find the failing field.
  2. 2.```bash
  3. 3.# Use ajv CLI to validate
  4. 4.npm install -g ajv-cli
  5. 5.ajv validate -s schema.json -d request.json -v
  6. 6.# Output shows the exact failing path:
  7. 7.# "data.address.zipCode" should be string
  8. 8.`
  9. 9.Check the API schema definition: Understand the expected structure.
  10. 10.```bash
  11. 11.# Get the API schema
  12. 12.curl -s https://api.example.com/openapi.json | jq '.components.schemas.CreateUserRequest'
  13. 13.# Or check the JSON schema directly
  14. 14.cat schema.json | jq '.properties.address.properties.zipCode'
  15. 15.`
  16. 16.Fix the request body to match the schema: Correct the nested field.
  17. 17.```json
  18. 18.// BEFORE: zipCode is a number but schema expects string
  19. 19.{
  20. 20."name": "John",
  21. 21."address": {
  22. 22."street": "123 Main St",
  23. 23."zipCode": 12345
  24. 24.}
  25. 25.}

// AFTER: zipCode as string { "name": "John", "address": { "street": "123 Main St", "zipCode": "12345" } } ```

  1. 1.Improve API validation error messages: Help consumers debug faster.
  2. 2.```python
  3. 3.# Python FastAPI - detailed validation errors
  4. 4.from fastapi import FastAPI, HTTPException
  5. 5.from pydantic import ValidationError

@app.exception_handler(ValidationError) async def validation_exception_handler(request, exc): return JSONResponse( status_code=400, content={ "error": "validation_failed", "details": [ {"field": str(e['loc']), "message": e['msg']} for e in exc.errors() ] } ) ```

  1. 1.Test the corrected request: Verify the fix.
  2. 2.```bash
  3. 3.curl -X POST https://api.example.com/users \
  4. 4.-H "Content-Type: application/json" \
  5. 5.-d '{"name":"John","address":{"street":"123 Main St","zipCode":"12345"}}'
  6. 6.# Should return 201 Created
  7. 7.`

Prevention

  • Provide detailed validation error messages with JSON paths to the failing fields
  • Publish OpenAPI/Swagger documentation with complete schema definitions
  • Include request schema examples in the API documentation
  • Implement client-side validation libraries that mirror the server schema
  • Test API requests against the published schema in CI/CD pipelines
  • Use contract testing (Pact) to catch schema mismatches before deployment