Error codes for machine consumption in Rest API

Introduction

Error codes help machines understand what went wrong when they talk to a server. They make it easy to fix problems automatically.

When a client sends bad data and the server needs to say 'something is wrong'.

When a user tries to access something they are not allowed to see.

When the server is busy or down and cannot handle the request.

When a requested item is not found on the server.

When the server successfully processes a request and wants to confirm it.

Syntax

Rest API

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error_code": 404,
  "message": "Resource not found"
}

The first line is the HTTP status line with a numeric code and a short phrase.

The body usually contains a JSON object with details like error_code and message.

Examples

This means the request worked fine and the server sends back data.

Rest API

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": {...}
}

This tells the client that the data sent was wrong or missing something.

Rest API

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error_code": 400,
  "message": "Invalid input data"
}

This means the client must log in or provide credentials to continue.

Rest API

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error_code": 401,
  "message": "Authentication required"
}

This shows the server had a problem and could not complete the request.

Rest API

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "error_code": 500,
  "message": "Server error, try again later"
}

Sample Program

This small web server returns an item name if it exists. If not, it sends a 404 error code with a message in JSON. Machines can read this to know the item was missing.

Rest API

from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/item/<int:item_id>')
def get_item(item_id):
    items = {1: 'apple', 2: 'banana'}
    if item_id not in items:
        return jsonify({"error_code": 404, "message": "Item not found"}), 404
    return jsonify({"item_id": item_id, "name": items[item_id]}), 200

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

Important Notes

Use standard HTTP status codes so machines and developers understand the meaning easily.

Always send error details in JSON for easy parsing by machines.

Keep error messages clear but avoid exposing sensitive information.

Summary

Error codes tell machines what happened during a request.

Use HTTP status codes with JSON messages for clear communication.

Proper error codes help automate fixes and improve user experience.

Practice

1.

What is the main purpose of using error codes in a REST API?

easy

A. To tell machines what happened during a request

B. To make the API run faster

C. To change the API's URL

D. To store user data securely

Solution

1. Step 1: Understand the role of error codes

   Error codes are used to communicate the result of a request to the client or machine.

2. Step 2: Identify the correct purpose

   The main purpose is to inform machines about success or failure of requests, enabling automated handling.

3. Final Answer:

   To tell machines what happened during a request -> Option A

4. Quick Check:

   Error codes = communicate request status [OK]

Hint: Error codes explain request results to machines [OK]

Common Mistakes:

• Thinking error codes speed up the API
• Confusing error codes with data storage
• Believing error codes change URLs

2.

Which HTTP status code correctly indicates a successful request in a REST API?

Choose the correct code:

easy

A. 404

B. 500

C. 200

D. 301

Solution

1. Step 1: Recall common HTTP status codes

   200 means OK (success), 404 means Not Found, 500 means Server Error, 301 means Redirect.

2. Step 2: Identify success code

   200 is the standard code for a successful HTTP request.

3. Final Answer:

   200 -> Option C

4. Quick Check:

   Success code = 200 [OK]

Hint: 200 means success in HTTP status codes [OK]

Common Mistakes:

• Choosing 404 thinking it means success
• Confusing 500 with success
• Selecting 301 which is a redirect

3.

Given this JSON error response from a REST API:

{
  "status": 404,
  "error": "Resource not found"
}

What does the 404 status code mean?

medium

A. The request was successful

B. The requested resource does not exist

C. The server encountered an error

D. The client is not authorized

Solution

1. Step 1: Understand HTTP 404 status code meaning

   404 means the requested resource was not found on the server.

2. Step 2: Match the error message with the code

   The message "Resource not found" confirms the meaning of 404.

3. Final Answer:

   The requested resource does not exist -> Option B

4. Quick Check:

   404 = resource missing [OK]

Hint: 404 means resource missing or not found [OK]

Common Mistakes:

• Thinking 404 means success
• Confusing 404 with server error
• Assuming 404 means unauthorized

4.

Look at this REST API error response snippet:

{
  "status": 200,
  "error": "Invalid input data"
}

What is wrong with this error code usage?

medium

A. Status 200 should not be used with an error message

B. The error message is missing a code

C. Status 200 means server error

D. The JSON format is incorrect

Solution

1. Step 1: Analyze the status code and message

   Status 200 means success, but the message says "Invalid input data" which is an error.

2. Step 2: Identify the mismatch

   Using 200 with an error message is incorrect; error codes like 400 should be used for invalid input.

3. Final Answer:

   Status 200 should not be used with an error message -> Option A

4. Quick Check:

   Status 200 = success, not error [OK]

Hint: Match error messages with proper error status codes [OK]

Common Mistakes:

• Ignoring mismatch between status and message
• Thinking 200 can mean error
• Assuming JSON format is wrong

5.

You want to design a REST API that returns error codes machines can easily understand and act on. Which approach is best?

Choose the best practice:

hard

A. Return random status codes to confuse attackers

B. Return only HTTP status codes without any message body

C. Return success status codes even when errors happen, but include error details in HTML

D. Return HTTP status codes with clear JSON error messages explaining the problem

Solution

1. Step 1: Understand best practices for machine-readable errors

   Machines need both status codes and clear JSON messages to understand errors and automate responses.

2. Step 2: Evaluate options

   Return HTTP status codes with clear JSON error messages explaining the problem provides both HTTP status codes and JSON messages, which is the recommended approach.

3. Final Answer:

   Return HTTP status codes with clear JSON error messages explaining the problem -> Option D

4. Quick Check:

   Status + JSON error message = best practice [OK]

Hint: Use status codes plus JSON messages for clear machine errors [OK]

Common Mistakes:

• Sending no message body with status codes
• Using success codes for errors
• Returning HTML instead of JSON for errors