MSDN Documentation

API Error Handling Guide

This guide outlines the standard error handling practices for our APIs, ensuring consistent and informative responses to client applications.

General Principles

When an error occurs, our APIs will return a JSON response containing detailed information about the problem. The response will include an HTTP status code that reflects the general nature of the error, and a JSON body with specific error details.

Error Response Format

All error responses adhere to the following JSON structure:

                
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request could not be processed due to invalid parameters.",
    "details": "The 'user_id' parameter must be a positive integer.",
    "field": "user_id",
    "status": 400
  }
}
                
            

• error: The root object containing error details.
• code: A machine-readable error code (e.g., INVALID_REQUEST, AUTHENTICATION_FAILED, RESOURCE_NOT_FOUND, INTERNAL_SERVER_ERROR).
• message: A human-readable, general description of the error.
• details: (Optional) More specific information about the error, useful for debugging.
• field: (Optional) The specific field in the request that caused the error, if applicable.
• status: The HTTP status code associated with the error.

Common HTTP Status Codes and Error Codes

400 Bad Request

Indicates that the request could not be understood or processed by the server due to malformed syntax or invalid parameters.

• INVALID_REQUEST: General invalid request.
• MISSING_PARAMETER: A required parameter is missing.
• INVALID_PARAMETER_FORMAT: A parameter has an incorrect format (e.g., expecting an integer, got a string).
• INVALID_PARAMETER_VALUE: A parameter has an invalid value (e.g., an out-of-range number).

401 Unauthorized

Indicates that the request requires authentication credentials that were not provided or were invalid.

• AUTHENTICATION_FAILED: Authentication credentials are invalid.
• MISSING_API_KEY: API key is not provided.

403 Forbidden

Indicates that the server understood the request but refuses to authorize it. The authenticated user does not have permission to perform the requested action.

• PERMISSION_DENIED: User lacks the necessary permissions.

404 Not Found

Indicates that the requested resource could not be found on the server.

• RESOURCE_NOT_FOUND: The requested resource does not exist.

429 Too Many Requests

Indicates that the user has sent too many requests in a given amount of time (rate limiting).

• RATE_LIMITED: Rate limit exceeded. Check response headers for retry information.

500 Internal Server Error

Indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

• INTERNAL_SERVER_ERROR: A generic server error.
• SERVICE_UNAVAILABLE: The requested service is temporarily unavailable.

                    
GET /api/v1/users/abc

// Response (400 Bad Request)
{
  "error": {
    "code": "INVALID_PARAMETER_FORMAT",
    "message": "Invalid format for user ID.",
    "details": "The 'user_id' parameter must be a numeric identifier.",
    "field": "user_id",
    "status": 400
  }
}
                    
                

                    
GET /api/v1/products/99999

// Response (404 Not Found)
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested product could not be found.",
    "details": "Product with ID '99999' does not exist.",
    "status": 404
  }
}
                    
                

Best Practices for API Consumers

• Always check the HTTP status code of the response.
• Parse the JSON response body to extract specific error codes and messages.
• Implement logic to handle different error codes gracefully.
• Log detailed error information for debugging purposes.
• Respect rate limiting headers and implement retry mechanisms with exponential backoff.