API Error Handling Standards | Azure API Management

API Error Handling Standards

Overview (Simple Explanation)

Proper error handling ensures your APIs return meaningful, consistent responses. This improves client integration, debugging, and operational reliability.

Key principles:

Use standardized HTTP status codes
Include clear error messages
Log errors for monitoring and troubleshooting

Step 1: Standardize HTTP Status Codes

Always use consistent HTTP response codes for your API endpoints:

200 OK: Successful response
201 Created: Resource created
400 Bad Request: Client input invalid
401 Unauthorized: Authentication required
403 Forbidden: Access denied
404 Not Found: Resource missing
500 Internal Server Error: Unexpected server error

Step 2: Return Structured Error Messages

Use a consistent JSON structure for errors. Example:

{
  "error": {
    "code": "InvalidParameter",
    "message": "The 'userId' parameter is missing",
    "details": [
      "userId cannot be empty",
      "Ensure userId is a valid GUID"
    ]
  }
}

This helps clients parse errors programmatically.

Step 3: Use APIM Policies for Error Handling

APIM allows custom policies to intercept errors and return consistent responses.


  
    
      
      {
        "error": {
          "code": "ResourceNotFound",
          "message": "Requested resource does not exist"
        }
      }

Step 4: Log Errors for Monitoring

Always log errors to track issues and support troubleshooting:

Enable diagnostics logs in APIM
Integrate with Application Insights
Include request details, status code, and error message

Step 5: Test Error Scenarios

Simulate common error scenarios to verify your handling:

Invalid parameters
Unauthorized access
Non-existing resources
Server-side failures

Final Understanding (One Line)

Standardize status codes + structured messages + log errors → Ensure reliable, predictable API behavior.

💡 Clarifications & FAQ

1. Why use structured error messages?

Structured JSON errors allow clients to parse responses programmatically and handle errors reliably.

2. How do I decide which HTTP status code to use?

Follow standard conventions: 4xx for client errors, 5xx for server errors, 2xx for success.

3. Can APIM automatically handle errors?

Yes, APIM policies can intercept responses and standardize them before sending to the client.

4. How do I test error handling?

Use tools like Postman or automated tests to simulate invalid requests, unauthorized access, or server failures.

5. Should I log all errors?

Log all unexpected or significant errors. Avoid logging sensitive data. Integrate with Application Insights or other monitoring tools.

6. What about custom error codes?

You can define your own error codes within the JSON response for clarity, e.g., "UserNotFound", "InvalidParameter".

📛 API Error Handling Standard

Proper error handling ensures your APIs return meaningful messages for developers and clients. In Azure APIM, this is done using the <on-error> policy.

Step 1: Access Error Handling Policy in Azure Portal

Go to Azure Portal → API Management → select your APIM instance.
Click APIs → select your API.
Click Design → then Policies tab.
Click the On-error tab to define custom error responses.

Step 2: Sample Error Handling Policy

<on-error>
  <choose>
    <when condition="@(context.Response.StatusCode == 400)">
      <return-response>
        <set-status code="400" reason="Bad Request" />
        <set-body>{
  "error": {
    "code": "BadRequest",
    "message": "The request is invalid. Please check your input."
  }
}</set-body>
      </return-response>
    </when>

    <when condition="@(context.Response.StatusCode == 401)">
      <return-response>
        <set-status code="401" reason="Unauthorized" />
        <set-body>{
  "error": {
    "code": "Unauthorized",
    "message": "Access token is missing or invalid."
  }
}</set-body>
      </return-response>
    </when>

    <otherwise>
      <return-response>
        <set-status code="520" reason="Unknown Error" />
        <set-body>{
  "error": {
    "code": "UnknownError",
    "message": "An unknown error occurred. Please contact support."
  }
}</set-body>
      </return-response>
    </otherwise>
  </choose>
</on-error>

Step 3: Test API

After saving the policy, test your API via the **Test** tab in Azure Portal or using Postman. You will see **custom error messages** returned based on the status code.

✅ API error handling configured successfully