HTTP
422 - Unprocessable Entity
Getting a 422 Unprocessable Entity means your request syntax is valid (unlike 400) but the data violates business rules or validation constraints—email format is wrong, required relationships are missing, or values break domain-specific rules. This client-side error (4xx) happens when servers validate request semantics after parsing succeeds. Most common in API calls where data passes JSON validation but fails business logic (e.g., duplicate email, invalid date ranges), but also appears when nested resources don't exist, foreign key constraints fail, or custom validation rules reject the data.
#Common Causes
- →Frontend: Email format validation fails (missing @, invalid domain). Date ranges are invalid (end date before start date). Required nested resources referenced but don't exist. Business rule violations (e.g., quantity exceeds stock). Data relationships are invalid (circular references, orphaned records).
- →Backend: Validation middleware catches semantic errors (express-validator, joi, zod). Database constraints fail (unique violations, foreign key errors). Business logic rejects valid syntax but invalid semantics. Nested resource validation fails. Custom validation rules trigger.
- →Infrastructure: API gateway enforces additional validation rules. WAF blocks certain data patterns. Load balancer validation layer rejects requests. Middleware stack validates before reaching application code.
✓Solutions
- 1Step 1: Diagnose - Check DevTools Network tab Response body—422 responses usually include detailed validation errors with field names and messages. Review each error to understand what failed.
- 2Step 2: Diagnose - Server logs show which validation rule failed. Review validation middleware output. Check database constraint violations. Examine business logic validation messages.
- 3Step 3: Fix - Client-side: Display validation errors to users with field-level feedback. Fix email formats, date ranges, and required fields. Check nested resource IDs exist before referencing. Implement client-side validation matching server rules.
- 4Step 4: Fix - Server-side: Return detailed 422 responses with field-level errors. Use validation libraries (express-validator, joi) for consistent error format. Validate business rules clearly. Check nested resources exist before processing.
- 5Step 5: Fix - Infrastructure: Review API gateway validation rules for conflicts. Check WAF pattern matching for false positives. Ensure load balancer doesn't add extra validation. Coordinate validation layers to avoid duplicate checks.
</>Code Examples
Fetch API: Handle 422 Validation Errors
1// Client-side: Display field-level validation errors
2async function createUser(userData) {
3 const response = await fetch('/api/users', {
4 method: 'POST',
5 headers: { 'Content-Type': 'application/json' },
6 body: JSON.stringify(userData),
7 });
8
9 if (response.status === 422) {
10 const errorData = await response.json();
11
12 // Display validation errors by field
13 if (errorData.errors && Array.isArray(errorData.errors)) {
14 errorData.errors.forEach(error => {
15 const field = error.field || error.path;
16 const message = error.message || error.msg;
17
18 // Show error next to form field
19 const fieldElement = document.querySelector(`[name="${field}"]`);
20 if (fieldElement) {
21 fieldElement.classList.add('error');
22 showFieldError(field, message);
23 }
24
25 console.error(`Validation error: ${field} - ${message}`);
26 });
27 }
28
29 throw new Error('Validation failed');
30 }
31
32 if (!response.ok) {
33 throw new Error(`Request failed: ${response.status}`);
34 }
35
36 return response.json();
37}
38
39function showFieldError(field, message) {
40 // Display error message in UI
41 const errorElement = document.createElement('div');
42 errorElement.className = 'error-message';
43 errorElement.textContent = message;
44 document.querySelector(`[name="${field}"]`).parentNode.appendChild(errorElement);
45}Express.js: Detailed 422 Validation Responses
1// Server-side: Return detailed validation errors
2const express = require('express');
3const { body, validationResult } = require('express-validator');
4const app = express();
5
6app.use(express.json());
7
8// Validation middleware
9const validateUser = [
10 body('email')
11 .isEmail()
12 .withMessage('Invalid email format')
13 .normalizeEmail(),
14 body('age')
15 .isInt({ min: 18, max: 120 })
16 .withMessage('Age must be between 18 and 120'),
17 body('startDate')
18 .isISO8601()
19 .withMessage('Invalid date format'),
20 body('endDate')
21 .isISO8601()
22 .withMessage('Invalid date format')
23 .custom((value, { req }) => {
24 if (new Date(value) < new Date(req.body.startDate)) {
25 throw new Error('End date must be after start date');
26 }
27 return true;
28 }),
29 body('departmentId')
30 .isInt()
31 .withMessage('Department ID must be an integer')
32 .custom(async (value) => {
33 // Check if department exists
34 const department = await db.departments.findById(value);
35 if (!department) {
36 throw new Error('Department does not exist');
37 }
38 return true;
39 }),
40];
41
42// Route with validation
43app.post('/api/users', validateUser, async (req, res) => {
44 const errors = validationResult(req);
45
46 if (!errors.isEmpty()) {
47 return res.status(422).json({
48 error: 'Unprocessable Entity',
49 message: 'Validation failed',
50 errors: errors.array().map(err => ({
51 field: err.path || err.param,
52 message: err.msg,
53 value: err.value,
54 })),
55 });
56 }
57
58 // Process valid request
59 const user = await db.users.create(req.body);
60 res.status(201).json(user);
61});Nginx: Pass Validation Errors to Client
1# Nginx: Ensure 422 responses reach client properly
2server {
3 listen 80;
4 server_name api.example.com;
5
6 location /api/ {
7 proxy_pass http://backend;
8 proxy_set_header Host $host;
9 proxy_set_header X-Real-IP $remote_addr;
10
11 # Pass through 422 responses with body
12 proxy_intercept_errors off;
13
14 # Don't cache 422 responses
15 proxy_cache_bypass $upstream_http_status;
16 add_header Cache-Control "no-store" always;
17
18 # Increase buffer for large error responses
19 proxy_buffer_size 4k;
20 proxy_buffers 8 4k;
21 }
22}↗Related Errors
Provider Information
This error code is specific to HTTP services. For more information, refer to the official HTTP documentation.