Error response structure in Rest API

Introduction

When something goes wrong in a web service, we need a clear way to tell the user what happened. An error response structure helps us send this information in a simple, organized way.

When a user sends wrong data to a web service.

When a requested resource is not found.

When the server has a problem and cannot complete the request.

When the user is not allowed to access certain information.

When the request format is incorrect or missing required parts.

Syntax

Rest API

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "string (optional)"
  }
}

The code is a short identifier for the error type.

The message explains the error in simple words.

Examples

This shows a simple error when something is not found.

Rest API

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

This error tells the user that some input is wrong and gives extra details.

Rest API

{
  "error": {
    "code": "400",
    "message": "Invalid input",
    "details": "The 'email' field is missing"
  }
}

Sample Program

This small web service returns a user name by ID. If the user ID is not found, it sends an error response with code 404 and a message.

Rest API

from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/user/<int:user_id>')
def get_user(user_id):
    users = {1: 'Alice', 2: 'Bob'}
    if user_id not in users:
        return jsonify({
            "error": {
                "code": "404",
                "message": "User not found"
            }
        }), 404
    return jsonify({"user": users[user_id]})

if __name__ == '__main__':
    app.run(debug=False)

Important Notes

Always use clear and simple messages so users understand the problem.

Include an error code to help developers handle errors programmatically.

Optional details can give more context but keep it short.

Summary

An error response structure helps communicate problems clearly.

It usually contains a code and a message.

Use it whenever your API needs to tell the user something went wrong.

Practice

1. What is the main purpose of an error response structure in a REST API?

easy

A. To clearly communicate what went wrong during a request

B. To speed up the API response time

C. To store user data securely

D. To format the successful response data

Solution

1. Step 1: Understand the role of error responses

   Error responses are sent when something goes wrong to inform the user or client about the issue.

2. Step 2: Identify the purpose of the error structure

   The structure helps communicate the problem clearly, usually with a code and message.

3. Final Answer:

   To clearly communicate what went wrong during a request -> Option A

4. Quick Check:

   Error response = clear problem message [OK]

Hint: Error responses explain problems clearly to users [OK]

Common Mistakes:

• Thinking error responses speed up API
• Confusing error response with data storage
• Assuming error response formats success data

2. Which of the following is the correct JSON syntax for a simple error response with code 404 and message "Not Found"?

easy

A. {"error": {code: 404, message: "Not Found"}}

B. {"error": {"code": 404, "message": "Not Found"}}

C. {"error": {"code": "404", "message": Not Found}}

D. {"error": {"code": 404, message: Not Found}}

Solution

1. Step 1: Check JSON key and string syntax

   Keys and string values must be in double quotes. Numbers like 404 do not need quotes.

2. Step 2: Identify the correct option

   {"error": {"code": 404, "message": "Not Found"}} uses correct quotes for keys and strings, and number 404 without quotes.

3. Final Answer:

   {"error": {"code": 404, "message": "Not Found"}} -> Option B

4. Quick Check:

   JSON keys and strings need double quotes [OK]

Hint: Use double quotes for keys and string values in JSON [OK]

Common Mistakes:

• Missing quotes around keys
• Using quotes around numbers
• Not quoting string values

3. Given this error response JSON:

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

What is the value of the message field?

medium

A. "error"

B. 401

C. null

D. "Unauthorized access"

Solution

1. Step 1: Locate the message field in the JSON

   The message field is inside the error object and has the value "Unauthorized access".

2. Step 2: Confirm the value type

   The value is a string, so it includes the quotes in JSON representation.

3. Final Answer:

   "Unauthorized access" -> Option D

4. Quick Check:

   message field value = "Unauthorized access" [OK]

Hint: Look inside error object for message value [OK]

Common Mistakes:

• Confusing code with message
• Selecting the key name instead of value
• Assuming null when field exists

4. You receive this error response from your API:

{"error": {"code": "400", "message": "Bad Request"}}

Why might this cause problems in your client code expecting code as a number?

medium

A. Because the error key is misspelled

B. Because the message is missing

C. Because the code is a string, not a number, causing type errors

D. Because the JSON is invalid

Solution

1. Step 1: Identify the data type of code field

   The code field is given as a string "400" instead of a number 400.

2. Step 2: Understand client expectations

   If client expects a number, receiving a string can cause type errors or failed comparisons.

3. Final Answer:

   Because the code is a string, not a number, causing type errors -> Option C

4. Quick Check:

   Type mismatch in code field causes errors [OK]

Hint: Check if code is number, not string, to avoid type errors [OK]

Common Mistakes:

• Ignoring type differences
• Assuming message is missing
• Thinking JSON is invalid

5. You want to design an error response structure that includes an error code, a message, and optionally a list of field errors for validation issues. Which JSON structure below correctly supports this?

hard

A. {"error": {"code": 422, "message": "Validation failed", "fields": [{"field": "email", "error": "Invalid format"}]}}

B. {"error": {"code": 422, "message": "Validation failed", "fields": "email: Invalid format"}}

C. {"error": {"code": 422, "message": "Validation failed", "fields": {"email": "Invalid format"}}}

D. {"error": {"code": 422, "message": "Validation failed", "fields": ["email", "Invalid format"]}}

Solution

1. Step 1: Understand the need for multiple field errors

   We want a list of objects, each with a field name and its error message.

2. Step 2: Check each option's fields format

   {"error": {"code": 422, "message": "Validation failed", "fields": [{"field": "email", "error": "Invalid format"}]}} uses an array of objects with field and error keys, which is clear and extensible.

3. Step 3: Identify why others are incorrect

   {"error": {"code": 422, "message": "Validation failed", "fields": "email: Invalid format"}} uses a string instead of structured data; {"error": {"code": 422, "message": "Validation failed", "fields": {"email": "Invalid format"}}} uses an object but not a list; {"error": {"code": 422, "message": "Validation failed", "fields": ["email", "Invalid format"]}} uses a list mixing field and message without keys.

4. Final Answer:

   {"error": {"code": 422, "message": "Validation failed", "fields": [{"field": "email", "error": "Invalid format"}]}} -> Option A

5. Quick Check:

   Use array of objects for detailed field errors [OK]

Hint: Use array of objects for multiple field errors [OK]

Common Mistakes:

• Using plain strings instead of structured objects
• Mixing field names and messages in arrays without keys
• Using object instead of list for multiple errors