Reading HTTP Error Messages in API Responses

422 = syntactically valid request, but semantically wrong — business validation failed:

The response body confirms this: "The request body contains invalid or missing fields." The JSON was parsed successfully (no syntax error), but the field values and presence don't meet the API's requirements.

HTTP status code anatomy:

• 2xx → Success (200 OK, 201 Created)
• 4xx → Client error — the request has a problem
• 5xx → Server error — the server failed to handle a valid request

422 vs. 400 (preview for Q4):

• 400 Bad Request → the request itself is malformed. Typical causes: invalid JSON, wrong Content-Type, missing required HTTP headers.
• 422 Unprocessable Entity → the request was received and parsed fine, but the data inside doesn't pass validation. Typical causes: wrong email format, missing required field, value out of range.

Why the distinction matters:
A developer receiving a 400 should fix how the request is formed. A developer receiving a 422 should fix the field values. These require different debugging approaches.

The request_id is a correlation identifier that links this response to server-side logs:

Notice that request_id in the JSON body ("req_8f3a2d1c9b04e7f6") matches the X-Request-ID HTTP response header. This is intentional: every log line on the server for this request is tagged with the same ID.

How it's used in practice:

1. A user reports: "I got an error around 14:32 UTC"
2. Support asks: "Can you share the request_id from the error response?"
3. User provides: req_8f3a2d1c9b04e7f6
4. Engineer runs: grep req_8f3a2d1c9b04e7f6 /var/log/api.log
5. All log lines for that exact request appear: input, validation steps, database calls, timing

Why this is better than a timestamp:
Many requests happen per second. A timestamp gives you dozens of candidates. A unique request_id gives you exactly one.

API design vocabulary:

• request_id / correlation_id / trace_id → different names for the same concept: a unique ID that follows a request through all systems
• distributed tracing → using correlation IDs to trace a request across multiple microservices
• X-Request-ID → a common HTTP response header convention for surfacing the ID

The details array gives field-by-field actionable fix instructions:

Each object in the details array contains:

• "field" → which field failed (e.g. "email")
• "issue" → the type of error (e.g. "invalid_format", "required_field_missing")
• "message" → a human-readable fix instruction with an example

Three specific fixes this error tells the developer to make:

1. email: currently in an invalid format → must look like user@example.com
2. date_of_birth: field is missing entirely → required when account_type is "verified"
3. phone: missing country code → must include it, e.g. +44 7700 900123

Why structured error responses are valuable:
A vague error like "Validation failed" forces the developer to guess. A structured response with field-level details tells them exactly what to change. This reduces support requests and speeds up integration.

API design vocabulary:

• validation error → a request field that fails a business rule
• invalid_format → the value is present but in the wrong format
• required_field_missing → a mandatory field was not included in the request body

400 = broken request format; 422 = broken field values:

HTTP 400 Bad Request — the server could not parse the request:

• The JSON body is malformed: {"email": "user@example.com" (missing closing brace)
• Wrong Content-Type header: sending JSON but declaring text/plain
• Required HTTP headers missing

The server never got to look at the field values — it couldn't even read the request.

HTTP 422 Unprocessable Entity — the server read the request, but values are invalid:

• JSON is valid, all headers correct
• But email is "not-an-email", or date_of_birth is missing, or age is -5

The server received and understood the request structure — it just cannot process the content.

Practical debugging decision tree:

• Got a 400? → Check your request format: Content-Type header, JSON syntax, required headers
• Got a 422? → Check your field values: formats, required fields, value constraints

Common confusion:
Some APIs use 400 for everything (both format and validation errors). This is technically valid but less informative. The 422 distinction is a best practice.

Structured errors enable machines to read and act on errors — plain text can only be read by humans:

What a client application can do with the structured response in the passage:

• Display field-specific errors in a form: The details array has "field": "email" → the UI can highlight the email input and show the message next to it. A plain text "Validation failed" cannot tell the UI which field to highlight.
• Programmatic error handling: Code can check if (error.code === 'VALIDATION_FAILED') and apply specific logic. With plain text, the code would need fragile string matching like if (text.includes("Validation")).
• Machine-readable: Monitoring tools, error trackers, and support dashboards can aggregate errors by code, by failing field, or by request_id.

Comparison:
Plain text: "Error: email is wrong, phone is wrong, date missing" — a human can read this, but a machine cannot reliably extract field names.
Structured JSON: each error is an object with consistent keys — any code consuming this API can reliably parse it.

API design vocabulary:

• machine-readable → data formatted so software can process it without human interpretation
• error envelope → the top-level structure wrapping an error (often { "error": { ... } })
• documentation_url → links the developer to full documentation for this error code