Error codes for machine consumption in Rest API - Step-by-Step Execution

Concept Flow - Error codes for machine consumption

Client sends request

↓

Server processes request

↓

Check for errors?

No→Send success response

Yes↓

Generate error code

↓

Send error response with code

↓

Client reads error code

↓

Client handles error accordingly

The client sends a request, the server checks for errors, sends back an error code if needed, and the client uses that code to decide what to do.

Execution Sample

Rest API

GET /api/data
Response: 404 Not Found
{
  "error_code": "NOT_FOUND",
  "message": "Data not found"
}

A client requests data, server responds with a 404 error code and a machine-readable error code in JSON.

Execution Table

Step	Action	Server Status	Response Code	Response Body
1	Client sends GET /api/data	Processing request	N/A	N/A
2	Server checks data existence	Data not found	N/A	N/A
3	Server generates error code	Error generated	404	{"error_code": "NOT_FOUND", "message": "Data not found"}
4	Server sends error response	Response sent	404	{"error_code": "NOT_FOUND", "message": "Data not found"}
5	Client receives response	Response received	404	{"error_code": "NOT_FOUND", "message": "Data not found"}
6	Client reads error_code	Error handled	404	Client decides next steps

💡 Execution stops after client receives and processes the error response.

Variable Tracker

Variable	Start	After Step 2	After Step 3	After Step 5	Final
request	None	GET /api/data	GET /api/data	GET /api/data	Processed
server_status	Idle	Checking data	Error generated	Response sent	Idle
response_code	None	None	404	404	404
response_body	None	None	{"error_code": "NOT_FOUND", "message": "Data not found"}	{"error_code": "NOT_FOUND", "message": "Data not found"}	{"error_code": "NOT_FOUND", "message": "Data not found"}
client_action	Waiting	Waiting	Waiting	Received error	Handled error

Key Moments - 2 Insights

Why does the server send both a numeric HTTP status code and a machine-readable error code?

The HTTP status code (like 404) tells the client the general error type, while the machine-readable error code (like "NOT_FOUND") gives a precise, consistent identifier for the error so the client can handle it programmatically. See execution_table rows 3 and 4.

What happens if the client ignores the error_code in the response body?

If the client ignores the error_code, it may not handle the error correctly or specifically. The client might only see the HTTP status but miss detailed info for proper action. See execution_table row 6 where client reads error_code to decide next steps.

Visual Quiz - 3 Questions

Look at the execution_table, what is the response_code at Step 3?

A 404

B 500

C 200

D 400

💡 Hint

Check the 'Response Code' column at Step 3 in the execution_table.

At which step does the client receive the error response?

A Step 4

B Step 5

C Step 2

D Step 6

💡 Hint

Look for when the client status changes to 'Response received' in the execution_table.

If the server sent a 200 status but included an error_code in the body, what would change in the execution_table?

A Response Code would be 404 and error_code would be missing

B Response Code and error_code would both be 200

C Response Code would be 200 but error_code still present in Response Body

D No change, response_code stays 404

💡 Hint

Think about how HTTP status and error_code are independent but usually consistent, see variable_tracker for response_code and response_body.

Concept Snapshot

Error codes for machine consumption:
- Server sends HTTP status code (e.g., 404) for general error type.
- Response body includes machine-readable error_code (e.g., "NOT_FOUND") for precise handling.
- Client reads both to decide next steps.
- This helps automated clients handle errors clearly and consistently.

Full Transcript

This visual trace shows how a client sends a request to a server, which checks for errors. If an error occurs, the server sends back an HTTP status code like 404 and a JSON body with a machine-readable error_code such as "NOT_FOUND". The client receives this response and reads the error_code to handle the error properly. The execution table tracks each step from request to client handling. Variables like response_code and response_body change as the server processes and responds. Key moments clarify why both codes are needed and what happens if the client ignores the error_code. Quiz questions test understanding of response codes and client-server interaction. This helps beginners see how error codes work for machines to understand and react to problems automatically.

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