422 Unprocessable Entity

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

curl -i -X POST https://api.example.com/users \
  -H 'Content-Type: application/json' \
  -d '{"email":"not-an-email"}'
# Read the response body for field-level errors
# Validate against OpenAPI/JSON Schema before sending

How to diagnose HTTP errors

HTTP status codes are a first classification, not a diagnosis. The essential split: 4xx means the request was wrong (fix the client), 5xx means the server failed to fulfil a valid request (fix the server). The subtlety is that reverse proxies and CDNs generate their own 5xx responses. A 502 or 504 from nginx tells you about nginx's relationship with the upstream, not about your application code.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Capture the full exchange with curl -v or curl -sD - -o /dev/null. Response headers frequently name the component that generated the error (Server:, Via:, X-Cache:).
2. Determine whether the response came from your application or from something in front of it. Add a unique header in your app and check whether it survives; if it is missing, a proxy answered.
3. For 502/504, check the upstream directly, bypassing the proxy. If the upstream is healthy, the problem is proxy timeouts, buffer sizes, or DNS re-resolution.
4. Follow redirects explicitly with curl -IL to catch loops. A redirect loop is usually an HTTPS-terminating proxy that does not forward X-Forwarded-Proto.
5. Correlate the request with server logs using a request ID. Guessing from the status code alone is the slowest way to debug HTTP.

Tools worth reaching for

• curl -v / -IL
• browser devtools Network tab
• access logs
• tcpdump / Wireshark
• httpstat

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 developer.mozilla.org

Related HTTP errors

• 100-continue timeout / Expect: 100-continue stallsThe client sent Expect: 100-continue and is waiting before streaming the body, but the proxy…
• 400 Bad RequestThe server could not parse the request due to malformed syntax: bad JSON body, illegal…
• 401 UnauthorizedThe request requires authentication credentials. The client must authenticate to get the…
• 402 Payment RequiredReserved in the original HTTP specification and now used by many SaaS APIs to signal that the…
• 403 ForbiddenThe server understood the request but refuses to authorise it. Often due to insufficient…
• 404 Not FoundThe requested resource could not be found on the server. URL may be incorrect or resource was…
• 409 ConflictThe request conflicts with the current resource state. Typical causes include duplicate…
• 410 GoneThe resource was intentionally removed and is not expected to return. Unlike 404, 410 tells…

See all 49 HTTP errors →

Browse other categories

• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
• Frontend 23Hydration mismatches, bundler resolution, layout shift and font loading.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.