API Error Design

API Error Design — API Error Design Patterns

A reference for error systems, message design, and recovery strategies used by the doc-writer and mock-tester agents when designing API error documentation and tests.

Target Agents

• doc-writer — Applied when writing error reference documentation
• mock-tester — Applied when designing error scenario tests

Error Code System Design

Hierarchical Error Code Structure

{DOMAIN}_{CATEGORY}_{DETAIL}

Examples:
AUTH_TOKEN_EXPIRED        -- Authentication > Token > Expired
ORDER_PAYMENT_DECLINED    -- Order > Payment > Declined
USER_VALIDATION_EMAIL     -- User > Validation > Email

Error Code Catalog by Domain

Authentication/Authorization (AUTH)

Validation (VALIDATION)

Resource (RESOURCE)

Rate Limit

Server (SERVER)

Error Response Structure Standard

Basic Structure

{
  "error": {
    "code": "AUTH_TOKEN_EXPIRED",
    "message": "Token has expired",
    "detail": "The access token has expired. Please refresh using your refresh token.",
    "timestamp": "2025-03-15T09:30:00Z",
    "requestId": "req_abc123def456",
    "path": "/api/v1/users/me"
  }
}

Validation Error (Per-Field)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input values are invalid",
    "errors": [
      {
        "field": "email",
        "code": "VALIDATION_FORMAT",
        "message": "Please enter a valid email address",
        "value": "invalid-email"
      },
      {
        "field": "password",
        "code": "VALIDATION_LENGTH",
        "message": "Password must be at least 8 characters",
        "constraint": { "min": 8 }
      }
    ]
  }
}

Error Message Writing Principles

Three Elements of a Good Error Message

1. What went wrong — Describe the problem
2. Why it went wrong — Explain the cause or constraint
3. How to fix it — Provide a specific action

Do / Don't

Multilingual Error Message Structure

{
  "error": {
    "code": "VALIDATION_REQUIRED",
    "message": "Required field is missing",
    "messageKey": "error.validation.required",
    "params": { "field": "email" }
  }
}

Retry/Fallback Strategy

Retry Eligibility

Exponential Backoff

wait_time = min(baseDelay * 2^attempt + jitter, maxDelay)

Example: baseDelay=1s, maxDelay=30s
Attempt 1: 1s + random(0~500ms)
Attempt 2: 2s + random(0~500ms)
Attempt 3: 4s + random(0~500ms)
Attempt 4: 8s + random(0~500ms)
Maximum 3-5 attempts

Error Test Scenario Matrix