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.

Practice

1. What is the main benefit of sending JSON error responses in nginx?

easy

A. They automatically fix server errors without manual intervention.

B. They make error information easy for applications to read and process.

C. They reduce the size of error messages to save bandwidth.

D. They prevent users from seeing any error messages.

Solution

1. Step 1: Understand JSON error response purpose

   JSON error responses format error details in a way apps can easily parse and handle.

2. Step 2: Compare options

   Only They make error information easy for applications to read and process. correctly states the benefit of JSON error responses; others are incorrect or unrelated.

3. Final Answer:

   They make error information easy for applications to read and process. -> Option B

4. Quick Check:

   JSON error responses = easy app reading [OK]

Hint: JSON errors help apps read errors clearly [OK]

Common Mistakes:

• Thinking JSON errors fix server issues automatically
• Believing JSON errors hide all error messages
• Assuming JSON errors reduce bandwidth significantly

2. Which nginx directive is used to specify a custom error page that returns JSON?

easy

A. error_page

B. listen

C. proxy_pass

D. server_name

Solution

1. Step 1: Identify directive for custom error pages

   The error_page directive tells nginx which page to serve on specific errors.

2. Step 2: Eliminate unrelated directives

   proxy_pass forwards requests, listen sets ports, server_name sets domain names; none define error pages.

3. Final Answer:

   error_page -> Option A

4. Quick Check:

   Custom error page directive = error_page [OK]

Hint: Use error_page to set custom error responses [OK]

Common Mistakes:

• Confusing proxy_pass with error_page
• Using listen or server_name for error handling
• Forgetting to set content type for JSON

3. Given this nginx config snippet, what is the JSON response body for a 404 error?

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

medium

A. 404 Not Found

B. Not Found

C. {"error":"Not Found"}

D. Error 404

Solution

1. Step 1: Analyze the error_page and location block

   The 404 error triggers /404.json, which is internal and returns JSON with content type application/json.

2. Step 2: Check the return statement

   The return sends status 404 with JSON string '{"error":"Not Found"}' as the body.

3. Final Answer:

   {"error":"Not Found"} -> Option C

4. Quick Check:

   Return JSON string = {"error":"Not Found"} [OK]

Hint: Look at return content for JSON body [OK]

Common Mistakes:

• Assuming default HTML error page is returned
• Ignoring internal directive effect
• Confusing status code text with response body

4. You configured nginx to return JSON errors but clients receive HTML error pages instead. What is the likely mistake?

medium

A. The server_name directive is not set.

B. The error_page directive is missing or incorrect.

C. The return directive uses invalid JSON syntax.

D. The internal directive is missing in the error location block.

Solution

1. Step 1: Understand internal directive role

   The internal directive prevents direct client access to error pages, ensuring nginx uses them only for error responses.

2. Step 2: Identify why HTML is returned

   If internal is missing, clients can access the error page URL directly, causing nginx to serve default HTML instead of JSON error.

3. Final Answer:

   The internal directive is missing in the error location block. -> Option D

4. Quick Check:

   Missing internal = HTML errors shown [OK]

Hint: Always mark error locations internal for JSON errors [OK]

Common Mistakes:

• Forgetting internal causes direct access to error pages
• Blaming server_name for error response format
• Assuming JSON syntax error causes HTML output

5. How would you configure nginx to return a JSON error response with status 500 and body {"error":"Server Error"} using an internal location?

hard

A. error_page 500 /500.json;
location = /500.json {
internal;
default_type application/json;
return 500 '{"error":"Server Error"}';
}

B. error_page 500 /500.html;
location = /500.html {
internal;
default_type text/html;
return 500 'Server Error';
}

C. location /500.json {
return 500 '{"error":"Server Error"}';
}

D. error_page 500 /500.json;
location /500.json {
default_type application/json;
return 500 '{"error":"Server Error"}';
}

Solution

1. Step 1: Use error_page to map 500 to JSON location

   The directive error_page 500 /500.json; tells nginx to use /500.json for 500 errors.

2. Step 2: Define internal location with JSON content type and return JSON body

   The location must be internal to prevent direct access, set default_type application/json;, and return the JSON string with status 500.

3. Step 3: Verify options

   error_page 500 /500.json; location = /500.json { internal; default_type application/json; return 500 '{"error":"Server Error"}'; } matches all requirements. error_page 500 /500.html; location = /500.html { internal; default_type text/html; return 500 '

   Server Error

   '; } uses HTML. The others lack the internal directive or miss the error_page directive.

4. Final Answer:

   error_page 500 /500.json; location = /500.json { internal; default_type application/json; return 500 '{"error":"Server Error"}'; } -> Option A

5. Quick Check:

   Use error_page + internal + JSON return [OK]

Hint: Map error_page, mark internal, set JSON content, return JSON [OK]

Common Mistakes:

• Omitting internal directive
• Using wrong content type
• Not escaping JSON properly
• Not mapping error_page to location