JSON error responses in Nginx - Step-by-Step Execution

Process Flow - JSON error responses

Client sends request

↓

Nginx receives request

↓

Check for errors

↓

Generate JSON

↓

error response

↓

Send JSON error response

↓

Client receives response

Nginx receives a request, checks for errors, and if found, generates and sends a JSON error response back to the client.

Execution Sample

Nginx

error_page 404 = /404.json;
location = /404.json {
  default_type application/json;
  return 404 '{"error":"Not Found"}';
}

This config sends a JSON error message when a 404 error occurs.

Process Table

Step	Action	Condition	Result	Response Sent
1	Client sends request to /missing	Nginx checks if /missing exists	No file found	No response yet
2	Nginx triggers error_page 404	404 error detected	Redirect to /404.json	No response yet
3	Nginx processes /404.json location	Set content type to application/json	Prepare JSON body	No response yet
4	Nginx returns 404 with JSON body	Return statement executed	Response body: {"error":"Not Found"}	Response sent with status 404 and JSON body
5	Client receives response	Status 404 with JSON body	Client can parse JSON error	Response complete

💡 Execution stops after sending JSON error response to client.

Status Tracker

Variable	Start	After Step 2	After Step 4	Final
request_uri	/missing	/missing	/404.json	/404.json
response_status	N/A	404	404	404
response_body	N/A	N/A	{"error":"Not Found"}	{"error":"Not Found"}
content_type	N/A	N/A	application/json	application/json

Key Moments - 3 Insights

Why does Nginx redirect to /404.json instead of sending a plain 404 page?

Because the error_page directive maps 404 errors to /404.json, so Nginx serves that location which returns JSON. See execution_table step 2 and 3.

How does Nginx know to send JSON content type?

The location /404.json sets default_type to application/json, ensuring the response header is correct. See execution_table step 3.

What happens if the return directive is missing in /404.json location?

Nginx would not send the JSON error body and might return an empty or default response. The return directive explicitly sends the JSON with status code. See execution_table step 4.

Visual Quiz - 3 Questions

Look at the execution table, what is the response_body at step 4?

A {"error":"Not Found"}

B Empty body

C HTML 404 page

D Plain text 'Not Found'

💡 Hint

Check the 'Response Sent' column at step 4 in the execution_table.

At which step does Nginx set the content type to application/json?

A Step 1

B Step 2

C Step 3

D Step 5

💡 Hint

Look at the 'Action' and 'Result' columns in execution_table step 3.

If the error_page directive was removed, what would happen when /missing is requested?

A Nginx sends default HTML 404 page

B Nginx sends JSON error response anyway

C Nginx returns 200 OK with empty body

D Nginx redirects to /404.json

💡 Hint

Refer to the role of error_page directive in execution_table step 2.

Concept Snapshot

Nginx JSON error responses:
- Use error_page to map errors to JSON endpoint
- Set default_type to application/json in location
- Use return with JSON body and status code
- Client receives JSON error instead of HTML
- Helps APIs send machine-readable errors

Full Transcript

This visual execution shows how Nginx handles JSON error responses. When a client requests a missing resource, Nginx detects a 404 error. Instead of sending a default HTML page, it redirects internally to /404.json as configured by error_page. The /404.json location sets the content type to application/json and returns a JSON body with an error message and 404 status. The client receives this JSON error response. Variables like request_uri, response_status, response_body, and content_type change accordingly during the steps. Key points include how error_page triggers the JSON response, setting content type, and the importance of the return directive. The quizzes test understanding of response body content, content type setting, and behavior without error_page.