api-error-handling

name	api-error-handling
description	Apply when designing error responses, implementing error handlers, and ensuring consistent error format across APIs.
version	1.1.0
tokens	~650
confidence	high
sources	["https://www.rfc-editor.org/rfc/rfc9457","https://datatracker.ietf.org/doc/html/rfc9110#section-6"]
last_validated	"2025-12-10T00:00:00.000Z"
next_review	"2025-12-24T00:00:00.000Z"
tags	["api","error-handling","backend","rest"]

When to Use

Apply when designing error responses, implementing error handlers, and ensuring consistent error format across APIs.

Patterns

Pattern 1: Standard Error Response Format

// Source: https://www.rfc-editor.org/rfc/rfc9457 (Problem Details)
interface ApiError {
  error: {
    code: string;           // Machine-readable code
    message: string;        // Human-readable message
    details?: ErrorDetail[];// Field-level errors
    requestId?: string;     // For debugging
  };
}

interface ErrorDetail {
  field: string;
  message: string;
  code?: string;
}

// Example response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format", "code": "INVALID_FORMAT" },
      { "field": "age", "message": "Must be positive", "code": "INVALID_RANGE" }
    ],
    "requestId": "req_abc123"
  }
}

Pattern 2: Error Class Hierarchy