api-error-handling（API error handling 文档）

API Error Handling

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

Overview

Build robust error handling systems with standardized error responses, detailed logging, error categorization, and user-friendly error messages. This skill covers the full lifecycle from throwing typed errors through logging, monitoring, and client-facing response formatting.

When to Use

• Handling API errors consistently across endpoints
• Debugging production issues with request tracing
• Implementing error recovery strategies (retry, circuit breaker)
• Monitoring and alerting on error rates
• Providing meaningful, actionable error messages to clients
• Validating request inputs before processing
• Tracking error patterns over time

Quick Start

Minimal standardized error response format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input validation failed",
    "statusCode": 422,
    "requestId": "req_abc123xyz789",
    "timestamp": "2025-01-15T10:30:00Z",
    "details": [
      { "field": "email", "message": "Invalid email format", "code": "INVALID_EMAIL" }
    ]
  }
}

Custom error class (Node.js):

class ApiError extends Error {
  constructor(code, message, statusCode = null, details = null) {
    super(message);
    this.code = code;
    this.statusCode = statusCode || ERROR_CODES[code]?.status || 500;
    this.details = details;
    this.timestamp = new Date().toISOString();
  }
}

// Usage
throw new ApiError("NOT_FOUND", "User not found", 404);
throw new ApiError("VALIDATION_ERROR", "Missing fields", 422, fieldErrors);

Reference Guides

Detailed implementations in the references/ directory:

Best Practices

✅ DO

• Use a consistent error response format across all endpoints
• Include requestId and traceId in every error for observability
• Log 5xx errors at ERROR level; log 4xx at WARN level
• Provide actionable error messages — tell the client what to fix
• Use standard HTTP status codes (4xx client errors, 5xx server errors)
• Implement retry with exponential backoff for transient failures
• Use circuit breakers to prevent cascade failures
• Validate inputs early and return all field errors at once
• Monitor error rates and alert on anomalous spikes

❌ DON'T

• Expose stack traces or internal implementation details to clients
• Return HTTP 200 for error responses
• Silently swallow errors
• Log sensitive data (passwords, tokens, PII)
• Use vague messages like "Something went wrong"
• Mix error handling logic with business logic
• Retry non-idempotent operations or client errors (4xx)
• Return different error shapes from different endpoints