HTTP Error Codes for Invalid Input: 400 vs 422 Explained
Explore which HTTP status codes to return when input data is invalid, including 400 vs 422, with actionable guidance for robust API validation and clear error payloads.
The HTTP status code most commonly used for invalid input is 400 Bad Request. For semantically invalid or failed validations, many APIs adopt 422 Unprocessable Entity. The choice hinges on whether the client sent syntactically malformed data (400) or well-formed data that fails business rules (422). Use 400 for parse/format errors and 422 for validation failures while keeping a consistent error payload that explains the issue.
What counts as invalid input in HTTP requests
Invalid input encompasses syntactic errors (malformed JSON, invalid encoding, broken headers), structural mistakes (missing required fields, invalid schema shapes), and content issues (out-of-range values, unsupported formats). When a client sends such data, the server must reject the request in a predictable way. This section clarifies how servers detect invalid input and why the distinction between syntactic invalidity and semantic invalidity matters for HTTP status codes. Invalid input isn’t limited to wrong values; it includes missing values, wrong data types, or mismatched content types. In RESTful APIs, triggers include missing path parameters, invalid query syntax, oversized payloads, and invalid JSON. In real-world systems, framing and encoding problems can also produce 400-level errors even if the business logic would be valid with different data. This nuance informs how you validate and respond to clients.
400 Bad Request vs 422 Unprocessable Entity: when to use each
The 400 Bad Request status code signals that the server cannot process the request due to client error—typically something syntactically wrong or clearly malformed. Conversely, 422 Unprocessable Entity indicates that the request is well-formed but the content failed validation rules or business logic. For example, a missing required field or a string that fails a format check could trigger 400, while a properly structured payload that violates domain rules (like an invalid date or a value outside allowed range) may warrant 422. Some API designers use 422 for all semantic validation failures to distinguish from parsing errors; others standardize on 400 with an explicit error payload. The choice affects client-side error handling, debugging workflows, and automated tests. As a rule, reserve 400 for syntactic/structural problems and 422 for semantic validation failures, and provide a consistent, machine-readable error payload that explains the cause and suggested remediation steps.
Implementing robust input validation: server-side + client hints
Robust input validation begins before data ever reaches business logic. On the server, adopt a layered approach: strict schema validation, explicit type coercion, and clear constraints. Use a schema library or manual checks to enforce required fields, allowed formats, and sensible ranges. On the client side, implement validation that catches obvious mistakes early, providing immediate feedback to users and reducing round-trips. Use content-type validation, length checks, and whitelist inputs where possible. When validation fails, return meaningful error payloads that help developers fix the problem quickly. Emphasize a consistent error structure (status code, error type, message, and field-level details) so clients can programmatically react. Finally, consider progressive enhancement: provide hints in client-side UI that align with server expectations, such as input masks or format previews.
Designing clear error responses (Problem Details) and standard messages
Standardized error payloads reduce debugging time. Use a machine-readable format such as a Problem Details object (RFC 7807) or a custom schema that mirrors problem type, title, status, detail, and instance. Include a pointer to the problematic field (e.g., "errors": {"email": "invalid format"}), and avoid leaking internal server information. For APIs accessible to a broad audience, provide a user-friendly message alongside a developer-oriented detail. When possible, supply a traceId or correlationId for debugging across distributed systems. Surface actionable remediation steps (e.g., 'provide a valid email address' or 'use a date in ISO-8601 format') to guide callers. Consistency across endpoints matters more than the exact wording of error text.
Common pitfalls and anti-patterns to avoid
Avoid returning 200 OK with an error flag in the body; callers then have to parse extra fields to detect failure. Do not mix error handling: reuse 400 for parsing errors and 422 for semantic validation without a consistent rule. Don’t leak stack traces or internal server details in production. Do not blanket-transform all input issues into a single generic message; provide specific field-level feedback. Finally, avoid large error payloads; use concise messages and attach a structured list of field errors when possible.
Testing strategies to catch invalid input errors early
Integrate input validation into unit, integration, and contract tests. Use property-based tests to explore edge cases; include boundary values for numeric fields and invalid formats. Simulate common client mistakes, such as missing fields, unexpected types, and oversized payloads. Use fuzz testing and negative scenarios, verifying that responses use the correct status codes and include helpful problem details. Maintain a robust test suite that checks for consistent error payload format across endpoints and versions, and enforce regression tests to prevent backsliding.
Real-world patterns across ecosystems: REST, GraphQL, gRPC
REST APIs generally rely on 400 vs 422 semantics. GraphQL often reports syntax errors in the query and field-level issues in the data, often within a normal HTTP 200 response but with an errors array in the body. gRPC uses status codes and trailers; invalid input typically yields INVALID_ARGUMENT. Across ecosystems, the goal is predictable, self-describing errors that guide clients to fix their requests quickly. Align your error handling with your API governance and developer experience guidelines, document your error model in a central reference, and ensure consistent identifiers across services.
Comparison of HTTP error codes for invalid input
| Code | Meaning | Typical Use |
|---|---|---|
| 400 Bad Request | Client sent malformed or invalid input | Parse errors, invalid JSON, missing required fields |
| 422 Unprocessable Entity | Valid JSON but semantically invalid | Validation failures, rule violations |
| 415 Unsupported Media Type | Request body format not supported | Client sends unsupported content type |
Frequently Asked Questions
What is the difference between 400 Bad Request and 422 Unprocessable Entity for invalid input?
400 signals syntactic or structural problems with the request, such as malformed JSON. 422 indicates that the request is well-formed but fails validation rules. Use the distinction consistently and provide a detailed error payload.
400 is for syntax or structure issues; 422 is for semantic validation problems.
Should a missing required field always trigger 400?
Not always. Some teams use 422 for missing or invalid field values to distinguish from parsing errors, but maintain a consistent rule across endpoints.
Consistency is key; pick 400 or 422 and apply it everywhere.
How should error payloads be structured?
Use a consistent schema (like Problem Details) including type, title, status, detail, and instance, plus a field-errors map where applicable.
Keep error details machine-friendly and consistent.
Is 415 ever appropriate for invalid input?
415 indicates an unsupported media type; use it when the Content-Type is not supported rather than for invalid input values.
Only use 415 when the content type itself is the problem.
How do GraphQL APIs report input errors?
GraphQL typically reports syntax errors in the query and field-level issues within the data, often inside a normal 200 response as part of an errors array.
GraphQL errors usually appear in the response body, not the HTTP status code.
“Invalid input should be treated as a validation problem surfaced through a clear, machine-readable error. Consistent status codes and detailed problem details reduce client-side guesswork.”
Top Takeaways
- Validate inputs early to catch issues before processing
- Prefer 400 for syntax/structure problems, 422 for semantic validation
- Return machine-readable problem details with clear field errors
- Avoid leaking internals; provide actionable remediation steps
- Test with boundary cases and negative scenarios regularly
