{
  "error": "error_type",
  "message": "Human-readable description",
  "code": "ERROR_CODE",
  "details": {}
}

{
  "error": "validation_error",
  "issues": [
    {
      "kind": "validation",
      "type": "required",
      "expected": "string",
      "received": "undefined",
      "message": "Required field",
      "path": [{ "type": "object", "key": "email" }]
    }
  ]
}

{
  "error": "bad_request",
  "message": "Invalid JSON in request body"
}

try {
  await fetch("/api/experiences", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(data),
  });
} catch (error) {
  if (error.status === 400) {
    console.error("Invalid request:", error.message);
    // Fix request data and retry
  }
}

{
  "error": "unauthorized",
  "message": "Authentication required"
}

X-Publishable-Key: pk_live_...
Authorization: Bearer <consumer_token>  (if authenticated)

Authorization: Bearer <clerk_jwt>

// Handle 401 errors
if (response.status === 401) {
  const error = await response.json();

  if (error.error === "token_expired") {
    // Refresh the token
    await client.auth.refresh();
    // Retry the request
    return retry();
  }

  // Re-authenticate
  await client.auth.login();
}

{
  "error": "forbidden",
  "message": "You don't have permission to access this resource"
}

if (response.status === 403) {
  // Check if it's a device mismatch
  const error = await response.json();

  if (error.code === "FP002") {
    showMessage("Please use your original device to complete this action.");
  } else {
    showMessage("You don't have access to this resource.");
  }
}

{
  "error": "not_found",
  "message": "Experience not found"
}

if (response.status === 404) {
  // Redirect to a fallback page
  navigate("/experiences");
  showMessage("This experience is no longer available.");
}

{
  "error": "conflict",
  "message": "Already in queue"
}

if (response.status === 409) {
  const error = await response.json();

  if (error.error === "already_in_queue") {
    // Get existing queue status instead
    const status = await client.queues.getStatus(queueId);
    updateUI(status);
  }
}

{
  "error": "validation_error",
  "issues": [
    {
      "kind": "validation",
      "type": "email",
      "expected": "valid email",
      "received": "not-an-email",
      "message": "Invalid email format",
      "path": [{ "type": "object", "key": "email" }]
    },
    {
      "kind": "validation",
      "type": "min_length",
      "expected": "8 characters",
      "received": "5 characters",
      "message": "Password must be at least 8 characters",
      "path": [{ "type": "object", "key": "password" }]
    }
  ]
}

if (response.status === 422) {
  const error = await response.json();

  if (error.error === "validation_error") {
    error.issues.forEach((issue) => {
      // Get the field path
      const field = issue.path[issue.path.length - 1]?.key || "root";

      // Display error on the form field
      setFieldError(field, issue.message);
    });
  }
}

{
  "error": "rate_limited",
  "message": "Too many requests"
}

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
Retry-After: 30

if (response.status === 429) {
  const retryAfter = parseInt(response.headers.get("Retry-After") || "30");

  showMessage(`Please wait ${retryAfter} seconds before trying again.`);

  // Automatically retry after the delay
  await sleep(retryAfter * 1000);
  return retry();
}

{
  "error": "internal_error",
  "message": "An unexpected error occurred",
  "requestId": "req_abc123xyz"
}

if (response.status === 500) {
  const error = await response.json();

  // Log for debugging
  console.error("Server error:", error.requestId);

  // Show user-friendly message
  showMessage("Something went wrong. Please try again.");

  // Retry with exponential backoff
  if (attempt < maxRetries) {
    await sleep(Math.pow(2, attempt) * 1000);
    return retry();
  }
}

{
  "error": "service_unavailable",
  "message": "Service temporarily unavailable"
}

if (response.status === 503) {
  // Show maintenance message
  showMessage("Service is temporarily unavailable. Please try again shortly.");

  // Retry with backoff
  const retryAfter = parseInt(response.headers.get("Retry-After") || "60");
  await sleep(retryAfter * 1000);
  return retry();
}

{
  "error": "validation_error",
  "issues": [
    {
      "kind": "validation",
      "type": "unique",
      "expected": "unique_value",
      "received": "duplicate_value",
      "message": "validation.unique",
      "path": [{ "type": "object", "key": "email" }]
    }
  ]
}

async function apiRequest<T>(url: string, options: RequestInit): Promise<T> {
  const response = await fetch(url, options);

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        // Handle authentication
        await handleUnauthorized(error);
        throw new AuthError(error);

      case 422:
        // Handle validation
        throw new ValidationError(error.issues);

      case 429:
        // Handle rate limiting
        const retryAfter = response.headers.get("Retry-After");
        throw new RateLimitError(parseInt(retryAfter || "30"));

      default:
        throw new ApiError(error);
    }
  }

  return response.json();
}

async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries?: number; baseDelay?: number } = {}
): Promise<T> {
  const { maxRetries = 3, baseDelay = 1000 } = options;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      // Don't retry client errors (4xx) except rate limits
      if (error.status >= 400 && error.status < 500 && error.status !== 429) {
        throw error;
      }

      if (attempt === maxRetries - 1) {
        throw error;
      }

      // Exponential backoff with jitter
      const delay = baseDelay * Math.pow(2, attempt) * (0.5 + Math.random() * 0.5);
      await sleep(Math.min(delay, 30000));
    }
  }

  throw new Error("Max retries exceeded");
}