Human-readable error messages in Rest API - Step-by-Step Execution

Concept Flow - Human-readable error messages

Client sends request

↓

Server processes request

↓

Error occurs?

No→Send success response

Yes↓

Generate error message

↓

Format message human-readable

↓

Send error response to client

The server checks for errors during request processing, creates a clear message if an error happens, and sends it back to the client.

Execution Sample

Rest API

def get_user(user_id):
    if user_id <= 0:
        return {"error": "Invalid user ID. Must be positive."}
    # fetch user logic
    return {"user": "User data here"}

This code checks if the user ID is valid and returns a clear error message if not.

Execution Table

Step	Input user_id	Condition	Action	Output
1	-1	user_id <= 0 is True	Return error message	{"error": "Invalid user ID. Must be positive."}
2	5	user_id <= 0 is False	Fetch user data	{"user": "User data here"}
3	0	user_id <= 0 is True	Return error message	{"error": "Invalid user ID. Must be positive."}

💡 Stops after returning either error or user data response

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3
user_id	undefined	-1	5	0
output	undefined	{"error": "Invalid user ID. Must be positive."}	{"user": "User data here"}	{"error": "Invalid user ID. Must be positive."}

Key Moments - 2 Insights

Why do we return a dictionary with an 'error' key instead of just a string?

Returning a dictionary with an 'error' key helps clients easily identify and handle errors, as shown in the execution_table rows 1 and 3.

What happens if the user_id is zero?

The condition user_id <= 0 is True, so the function returns the error message, as seen in execution_table row 3.

Visual Quiz - 3 Questions

Look at the execution_table, what is the output when user_id is 5?

A {"error": "Invalid user ID. Must be positive."}

B {"user": "User data here"}

C None

D An exception is raised

💡 Hint

Check execution_table row 2 under Output column

At which step does the function return an error message?

A Step 2

B Step 3 only

C Step 1 and Step 3

D No error message is returned

💡 Hint

Look at execution_table rows 1 and 3 under Action and Output

If we change the condition to user_id < 0, what happens when user_id is 0?

A Returns user data

B Returns error message

C Raises exception

D Returns None

💡 Hint

Check how condition user_id <= 0 vs user_id < 0 affects step 3 in variable_tracker

Concept Snapshot

Human-readable error messages:
- Check for errors in input or processing
- Return clear, simple messages in a structured format (like JSON)
- Use keys like 'error' to help clients detect problems
- Avoid technical jargon
- Always send a response explaining what went wrong

Full Transcript

This visual trace shows how a REST API function handles errors by checking the user_id input. If the user_id is zero or negative, the function returns a JSON object with an 'error' key and a clear message. If the user_id is positive, it returns user data. The execution table tracks each step, showing conditions checked and outputs returned. The variable tracker follows user_id and output values through each step. Key moments clarify why structured error messages are used and what happens with boundary values. The quiz tests understanding of outputs and condition effects. This helps beginners see how to make APIs send friendly error messages clients can understand.

Practice

1.

What is the main purpose of human-readable error messages in a REST API?

easy

A. To confuse users with complex codes

B. To hide all error details from users

C. To make error messages as technical as possible

D. To explain problems in simple words for users

Solution

1. Step 1: Understand the role of error messages

   Error messages should help users understand what went wrong.

2. Step 2: Identify the best description

   Human-readable means simple and clear, not technical or confusing.

3. Final Answer:

   To explain problems in simple words for users -> Option D

4. Quick Check:

   Human-readable = simple explanation [OK]

Hint: Think: error messages should help, not confuse [OK]

Common Mistakes:

• Choosing technical jargon instead of simple words
• Assuming error messages should hide details
• Confusing human-readable with code-only messages

2.

Which of the following is the correct JSON format for a human-readable error message in a REST API response?

{
  "error": {
    "code": 404,
    "message": "Resource not found"
  }
}

easy

A. { error: 404, message: 'Not found' }

B. { "error": { "code": 404, "message": "Resource not found" } }

C. { "code": 404, "msg": "Not found" }

D. { error_code: 404, error_message: 'Resource missing' }

Solution

1. Step 1: Check JSON syntax correctness

   Valid JSON requires double quotes around keys and string values.

2. Step 2: Match the expected structure

   The error object should contain code and message keys with clear names.

3. Final Answer:

   { "error": { "code": 404, "message": "Resource not found" } } -> Option B

4. Quick Check:

   Valid JSON with clear keys = { "error": { "code": 404, "message": "Resource not found" } } [OK]

Hint: Look for double quotes and clear key names in JSON [OK]

Common Mistakes:

• Using single quotes instead of double quotes in JSON
• Missing nested error object structure
• Using incorrect key names like 'msg' or 'error_code'

3.

Given this API response code snippet, what will be the output message?

response = {
  "status": 400,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Input value is not valid"
  }
}
print(response["error"]["message"])

medium

A. Input value is not valid

B. 400

C. INVALID_INPUT

D. KeyError

Solution

1. Step 1: Access nested dictionary keys

   response["error"] gives the nested dictionary, then ["message"] accesses the message string.

2. Step 2: Print the message value

   The value of response["error"]["message"] is "Input value is not valid".

3. Final Answer:

   Input value is not valid -> Option A

4. Quick Check:

   Nested key access = message string [OK]

Hint: Follow dictionary keys step-by-step to find the message [OK]

Common Mistakes:

• Printing the error code instead of message
• Confusing status code with error message
• Trying to access keys incorrectly causing KeyError

4.

Identify the error in this REST API error response JSON and fix it for proper human-readable message format:

{
  error: {
    code: 401,
    message: 'Unauthorized access'
  }
}

medium

A. Remove the error object and keep only code and message

B. Change code 401 to string '401'

C. Replace single quotes with double quotes and add quotes around keys

D. Add a status key with value 'error'

Solution

1. Step 1: Check JSON syntax rules

   JSON keys and string values must be in double quotes, not single quotes or unquoted.

2. Step 2: Fix the JSON format

   Add double quotes around keys (error, code, message) and change single quotes to double quotes.

3. Final Answer:

   Replace single quotes with double quotes and add quotes around keys -> Option C

4. Quick Check:

   Valid JSON needs double quotes on keys and strings [OK]

Hint: JSON keys and strings always need double quotes [OK]

Common Mistakes:

• Using single quotes for strings in JSON
• Leaving keys unquoted causing syntax errors
• Changing numeric codes to strings unnecessarily

5.

You want to design a REST API error response that helps users fix input errors quickly. Which approach is best?

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Email format is incorrect",
    "field": "email",
    "suggestion": "Use a valid email like [e-mail]"
  }
}

hard

A. Include error code, message, field name, and suggestion for fix

B. Only include a generic error message without details

C. Return HTTP 200 status with error details inside

D. Send error details only in server logs, not in response

Solution

1. Step 1: Identify helpful error response elements

   Clear code, message, field, and suggestion guide users to fix errors.

2. Step 2: Compare options for user-friendliness

   Include error code, message, field name, and suggestion for fix provides detailed, human-readable info; others hide or confuse users.

3. Final Answer:

   Include error code, message, field name, and suggestion for fix -> Option A

4. Quick Check:

   Detailed, clear errors improve user experience [OK]

Hint: Add suggestions and field info for clearer error messages [OK]

Common Mistakes:

• Returning generic messages without guidance
• Using HTTP 200 for errors causing confusion
• Hiding error details from users