{
  "error": {
    "code": "DOCUMENT_NOT_FOUND",
    "message": "The requested document could not be found",
    "details": {
      "document_id": "123e4567-e89b-12d3-a456-426614174000",
      "workspace_id": "workspace_abc123"
    },
    "request_id": "req_1234567890abcdef",
    "timestamp": "2025-01-07T10:30:00Z"
  }
}

class MateriAPIError extends Error {
  constructor(
    public status: number,
    public code: string,
    public message: string,
    public details?: Record<string, unknown>,
    public requestId?: string
  ) {
    super(message);
    this.name = 'MateriAPIError';
  }
}

async function handleResponse(response: Response) {
  if (response.ok) {
    return response.json();
  }

  const error = await response.json();
  throw new MateriAPIError(
    response.status,
    error.error.code,
    error.error.message,
    error.error.details,
    error.error.request_id
  );
}

async function apiCall(endpoint: string, options?: RequestInit) {
  try {
    const response = await fetch(`https://api.materi.dev/v1${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json',
        ...options?.headers,
      },
    });
    return handleResponse(response);
  } catch (error) {
    if (error instanceof MateriAPIError) {
      switch (error.code) {
        case 'TOKEN_EXPIRED':
          await refreshToken();
          return apiCall(endpoint, options);

        case 'RATE_LIMIT_EXCEEDED':
          const retryAfter = 60; // seconds
          await delay(retryAfter * 1000);
          return apiCall(endpoint, options);

        case 'VERSION_CONFLICT':
          // Handle conflict resolution
          throw error;

        default:
          throw error;
      }
    }
    throw error;
  }
}

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const isRetryable = [500, 502, 503, 504, 429].includes(error.status);

      if (!isRetryable || attempt === maxRetries) {
        throw error;
      }

      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      console.log(`Retry ${attempt + 1}/${maxRetries} after ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "fields": [
        {
          "field": "title",
          "code": "TITLE_TOO_LONG",
          "message": "Title must be 500 characters or less",
          "value_provided": "Very long title...",
          "max_length": 500
        },
        {
          "field": "email",
          "code": "INVALID_EMAIL_FORMAT",
          "message": "Email format is invalid",
          "value_provided": "not-an-email"
        }
      ]
    },
    "request_id": "req_abc123"
  }
}

Request ID: req_1234567890abcdef
Timestamp: 2025-01-07T10:30:00Z
Action: Creating document in workspace ws_abc123
Error: INSUFFICIENT_PERMISSIONS