Error response format in Rest API

Introduction

When something goes wrong in a web service, we need to tell the user clearly what happened. An error response format is a simple way to share this information.

When a user sends wrong data to a web service.

When a requested resource is not found on the server.

When the user is not allowed to access certain information.

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

When the user tries to do something that is not allowed.

Syntax

Rest API

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

The code is a short identifier for the error.

The message explains the error in simple words.

Examples

This means the requested page or data was not found.

Rest API

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

This tells the user they must log in first.

Rest API

{
  "error": {
    "code": "401",
    "message": "Unauthorized",
    "details": "You need to log in to access this resource."
  }
}

Sample Program

This small web service returns an item by its ID. If the item is missing, it sends a clear error response with code 404 and a message.

Rest API

from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/data/<int:item_id>')
def get_data(item_id):
    data_store = {1: 'apple', 2: 'banana'}
    if item_id not in data_store:
        return jsonify({
            "error": {
                "code": "404",
                "message": "Item not found",
                "details": f"No item with id {item_id} exists."
            }
        }), 404
    return jsonify({"item": data_store[item_id]})

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

Important Notes

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

Include HTTP status codes like 404 or 401 to help developers handle errors properly.

Optional details can give extra info but keep it short.

Summary

Error response format helps communicate problems clearly in web services.

It usually includes a code, a message, and sometimes extra details.

Using standard formats makes it easier for users and developers to understand errors.

Practice

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

easy

A. To speed up the API response time

B. To clearly communicate what went wrong during a request

C. To encrypt the data sent to the client

D. To store user information securely

Solution

1. Step 1: Understand the role of error responses

   Error responses tell the client what problem happened when processing their request.

2. Step 2: Identify the main goal

   The main goal is to communicate the error clearly so the client can handle it properly.

3. Final Answer:

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

4. Quick Check:

   Error response purpose = clear communication [OK]

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

Common Mistakes:

• Thinking error responses speed up API
• Confusing error format with encryption
• Assuming error responses store data

2. Which of the following is a correct JSON structure for a simple error response in a REST API?

easy

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

B. {"status": 200, "message": "Success"}

C. {"data": {"id": 1, "name": "Item"}}

D. {"error_code": "404", "error_msg": "Not Found"}

Solution

1. Step 1: Identify standard error response keys

   Common keys include "error", "code", and "message" to describe the problem.

2. Step 2: Check each option

   {"error": {"code": 404, "message": "Not Found"}} uses "error" with "code" and "message" correctly in JSON format.

3. Final Answer:

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

4. Quick Check:

   Standard error keys = code and message [OK]

Hint: Look for 'error', 'code', and 'message' keys in JSON [OK]

Common Mistakes:

• Confusing success response with error
• Using wrong key names like error_code
• Missing nested error object

3. Given this error response JSON:

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

What HTTP status code should the API return?

medium

A. 401

B. 500

C. 404

D. 200

Solution

1. Step 1: Match error code to HTTP status

   The error code 401 means "Unauthorized", which is an HTTP status code for authentication failure.

2. Step 2: Confirm correct HTTP status

   The API should return HTTP status 401 to match the error code in the response body.

3. Final Answer:

   401 -> Option A

4. Quick Check:

   Error code 401 = HTTP status 401 [OK]

Hint: Match error code with HTTP status code [OK]

Common Mistakes:

• Returning 200 for error responses
• Confusing 401 with 404
• Using 500 for client errors

4. You receive this error response from an API:

{"error": {"code": "403", "message": "Forbidden"}}

But your client expects the code as an integer. What is the best fix?

medium

A. Change the message to "Access Denied"

B. Remove the code field entirely

C. Change the code value to an integer 403 in the response

D. Wrap the code in quotes to make it a string

Solution

1. Step 1: Identify data type mismatch

   The code is a string "403" but the client expects an integer 403.

2. Step 2: Fix the data type in the response

   Change the code value from a string to an integer to match client expectations.

3. Final Answer:

   Change the code value to an integer 403 in the response -> Option C

4. Quick Check:

   Match data types for code field [OK]

Hint: Ensure error code data type matches client expectation [OK]

Common Mistakes:

• Removing important error fields
• Changing message instead of code type
• Leaving code as string when integer needed

5. You want to design an error response format that includes an error code, a message, and optional details for debugging. Which JSON structure below best fits this need?

hard

A. {"error": "Bad Request", "code": 400}

B. {"status": "error", "code": 400, "msg": "Bad Request"}

C. {"error_code": 400, "error_message": "Bad Request"}

D. {"error": {"code": 400, "message": "Bad Request", "details": "Missing 'id' parameter"}}

Solution

1. Step 1: Check required fields in each option

   We need code, message, and optional details inside a clear error object.

2. Step 2: Evaluate each JSON structure

   {"error": {"code": 400, "message": "Bad Request", "details": "Missing 'id' parameter"}} includes all three: code, message, and details nested inside "error".

3. Final Answer:

   {"error": {"code": 400, "message": "Bad Request", "details": "Missing 'id' parameter"}} -> Option D

4. Quick Check:

   Include code, message, and details in error object [OK]

Hint: Include optional details inside error object for clarity [OK]

Common Mistakes:

• Omitting details field
• Using inconsistent key names
• Not nesting error info properly