JSON error responses in Nginx - Mini Project: Build & Apply

JSON Error Responses in Nginx

📖 Scenario: You are setting up a web server using Nginx. You want to make sure that when users encounter errors like 404 or 500, they get a clear message in JSON format instead of the default HTML error page.

🎯 Goal: Configure Nginx to return JSON formatted error responses for HTTP status codes 404 and 500.

📋 What You'll Learn

Create a basic Nginx server block configuration

Add a variable to hold the JSON error message

Use the error_page directive to handle 404 and 500 errors

Return the JSON error message with the correct content type

Test the configuration by simulating 404 and 500 errors

💡 Why This Matters

🌍 Real World

Web servers often need to return error messages in JSON format for APIs or modern web apps that expect JSON responses instead of HTML error pages.

💼 Career

Knowing how to customize error responses in Nginx is a valuable skill for DevOps engineers and backend developers managing web infrastructure.

1

Create a basic Nginx server block

Create a basic Nginx server block listening on port 80 with the server name localhost. Inside the server block, add a location / block that returns a 200 status with the text "Welcome to Nginx".

Nginx

# Your code here

Need a hint?

Use server {} block with listen 80; and server_name localhost;. Inside location / {}, use return 200 'Welcome to Nginx';.

2

Add a variable for JSON error message

Inside the server block, create a variable called $json_error that holds the JSON string {"error": "Resource not found"}.

Nginx

server {
    listen 80;
    server_name localhost;

    # Define JSON error message variable
    # Your code here

    location / {
        return 200 'Welcome to Nginx';
    }
}

Need a hint?

Use the set directive to assign the JSON string to $json_error.

3

Configure error_page for 404 and 500 errors

Add error_page directives inside the server block to handle HTTP status codes 404 and 500. For both errors, redirect to /json_error location.

Nginx

server {
    listen 80;
    server_name localhost;

    set $json_error '{"error": "Resource not found"}';

    # Add error_page directives for 404 and 500
    # Your code here

    location / {
        return 200 'Welcome to Nginx';
    }
}

Need a hint?

Use error_page 404 /json_error; and error_page 500 /json_error; inside the server block.

4

Create /json_error location to return JSON error

Add a location /json_error block inside the server block. Inside it, set the Content-Type header to application/json and return the $json_error variable with status 200.

Nginx

server {
    listen 80;
    server_name localhost;

    set $json_error '{"error": "Resource not found"}';

    error_page 404 /json_error;
    error_page 500 /json_error;

    location / {
        return 200 'Welcome to Nginx';
    }

    # Add location /json_error block below
    # Your code here
}

Need a hint?

Use location /json_error {} with default_type application/json; and return 200 $json_error;.