Error handling is critical in any application to ensure users receive clear, actionable feedback when something goes wrong. With over 18 years of tech solution-building experience, I’ve seen developers focus solely on writing code while neglecting error handling, leaving it to the testing team. However, by investing just a little effort into unit testing and proper error handling, the application performance can be improved significantly. In this TechConcept, we’ll explore common error handling approaches, such as using standard HTTP response codes, custom error responses, and best practices for delivering helpful messages. We’ll also look at how to implement these techniques with code examples.

Standard HTTP Response Codes

HTTP response codes provide a universal way to indicate the result of a request. By using these codes effectively, developers can communicate whether a request succeeded or encountered issues.

Common HTTP Response Codes:

• 200 OK: The request was successful.
• 201 Created: A new resource was successfully created.
• 400 Bad Request: The request was malformed or invalid.
• 401 Unauthorized: Authentication is required or failed.
• 403 Forbidden: The client doesn’t have permission to access the resource.
• 404 Not Found: The requested resource doesn’t exist.
• 500 Internal Server Error: The server encountered an unexpected condition.

Pseudo Code:

// Handling a client request and returning appropriate response codes
if (isValidRequest(request)) {
    return { status: 200, message: "Success" };
} else if (isBadRequest(request)) {
    return { status: 400, message: "Bad Request: Invalid data provided" };
} else {
    return { status: 500, message: "Internal Server Error or under maintenance, connect back after some time" };
}

Use Case: User Registration API

When a user submits a registration form with missing or invalid data, the server responds with a 400 Bad Request, providing feedback on what was wrong with the submission. If the data is correct, the server responds with 201 Created, confirming successful registration.

Custom Error Responses

While HTTP response codes are helpful, custom error responses specific to application provide more detailed information, improving clarity for users and developers alike. Custom responses can include additional error codes, descriptions, and potential fixes.

Best Practices for Custom Error Responses:

• Error Code: A unique identifier for the error.
• Error Message: A user-friendly description of the issue.
• Details: Any extra information for developers.
• Suggested Fixes: Steps users can take to resolve the error.

Pseudo Code:

// Example custom error response for invalid input
{
  "error_code": "INVALID_INPUT",
  "message": "The provided input does not match the expected format.",
  "details": "Field 'email' is missing or incorrectly formatted.",
  "resolution": "Please enter a valid email address in the format '[email protected]'."
}

Use Case: Order Management System

In an order management API, if a user submits an order with an invalid product ID, the service can return a custom error like INVALID_PRODUCT_ID, providing additional context and suggestions for correction.

Graceful Error Handling

Graceful error handling ensures that APIs continue to provide useful feedback even when unexpected conditions occur. It helps prevent crashes and provides a consistent experience for users by catching errors and returning appropriate responses.

Techniques for Graceful Error Handling:

• Exception Handling: Catch and handle errors without crashing the system.
• Retry Mechanism: Automatically retry failed operations when possible.
• Fallback Responses: Provide alternatives if the primary action fails.
• Detailed Validation Messages: Return specific validation errors for user input issues.

Pseudo Code:

// Gracefully handling exceptions and retries
try {
    let product = fetchProduct(productId);
    return { status: 200, data: product };
} catch (ProductNotFoundError) {
    return { status: 404, message: "Product not found" };
} catch (DatabaseTimeoutError) {
    retryFetchProduct(productId); // Retry fetching product
    return { status: 500, message: "Server error: Please try again later." };
}

Use Case: E-Commerce API

When an API fails to retrieve product details due to a timeout, it retries the operation. If the retry also fails, it responds with a 500 Internal Server Error, informing the user to try again later without crashing the service.

Providing Helpful Error Messages

Providing clear, actionable error messages is critical for enhancing the user experience. A helpful message should explain what went wrong and offer solutions where possible.

Tips for Crafting Helpful Error Messages:

• Clarity: Avoid technical jargon; explain the issue in simple terms.
• Context: Include details that help the user understand the problem.
• Solutions: Where applicable, suggest how the user can fix the error.
• Avoid Blame: Focus on fixing the issue rather than blaming the user.

Pseudo Code:

{
  "error_code": "INVALID_EMAIL",
  "message": "The email address provided is invalid.",
  "resolution": "Please ensure the email is in the format '[email protected]'."
}

Use Case: Login API

When a user enters an invalid email during login, the API can return a helpful error response like INVALID_EMAIL, explaining the format issue and providing an example of correct input.

Error Logging for Debugging

For developers, logging errors is essential for debugging and improving system stability. Logs should capture detailed technical information, such as stack traces and request data, without exposing this information to the user.

Key Components for Error Logging:

• Error Type: Categorize the error (e.g., database, validation, authentication).
• Timestamp: Record the exact time of the error.
• Request Details: Capture the request context (e.g., headers, payload).
• Stack Trace: Include the stack trace for internal troubleshooting.

Pseudo Code:

// Log error details for internal troubleshooting
logError({
    timestamp: new Date(),
    errorType: "DatabaseError",
    requestId: request.id,
    stackTrace: getStackTrace(error)
});

Use Case: Support Ticket System

When a user encounters a database error while submitting a support ticket, the error is logged with details like the timestamp, error type, and request data. This helps developers diagnose the issue while returning a generic error message to the user.

Testing Error Scenarios

Regularly testing for potential error scenarios ensures that your API handles unexpected conditions gracefully. This includes testing for invalid inputs, service timeouts, and authentication failures.

Error Scenarios to Test:

• Invalid Input: Simulate malformed or incomplete data.
• Timeouts: Simulate slow or unresponsive services.
• Service Failures: Test scenarios where dependent services are unavailable.
• Authentication Failures: Test expired or invalid tokens.

Example Code:

// Test for invalid input in the registration form
let response = submitRegistration({ email: "invalid-email" });
assert(response.status === 400);
assert(response.message === "Invalid email address format.");

Use Case: User Registration System

In an automated testing suite, the system tests for invalid email formats and service timeouts to ensure the API responds gracefully, returning specific and helpful error messages.

My Tech Advice: Gracefully managing errors, not only minimises web-service disruption but also maintain user trust. Implementing effective error handling ensures that your web services provide users with meaningful feedback, even in failure scenarios. By utilizing standard HTTP response codes, creating custom error messages, practicing graceful exception handling, and logging errors for debugging, you can build robust, user-friendly APIs. By following these best practices, you can create a more resilient web service that handles errors smoothly and provides a better user experience.

#AskDushyant

#TechConcept #TechAdvice #ErrorHandling #HTTP #ErrorCode #WebService #MicroService