{
  "error": "Error type or message",
  "message": "Human-readable description (optional)",
  "details": [
    {
      "field": "fieldName",
      "message": "Field-specific error message"
    }
  ]
}

HTTP/1.1 401 Unauthorized

{
  "error": "Authentication required"
}

HTTP/1.1 401 Unauthorized

{
  "error": "invalid refresh token"
}

HTTP/1.1 401 Unauthorized

{
  "error": "Secret key required"
}

HTTP/1.1 400 Bad Request

{
  "error": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "capacity",
      "message": "Must be a positive integer"
    }
  ]
}

HTTP/1.1 400 Bad Request

{
  "error": "Validation failed",
  "details": [
    {
      "field": "name",
      "message": "Required"
    }
  ]
}

HTTP/1.1 400 Bad Request

{
  "error": "Validation failed",
  "details": [
    {
      "field": "slug",
      "message": "Already taken"
    }
  ]
}

HTTP/1.1 404 Not Found

{
  "error": "Experience not found"
}

HTTP/1.1 409 Conflict

{
  "error": "Sync already in progress"
}

HTTP/1.1 423 Locked
Retry-After: 2024-12-01T09:00:00Z

{
  "error": "Queue is not open yet"
}

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "error": "Queue is full"
}

HTTP/1.1 400 Bad Request

{
  "error": "Auction is closed"
}

HTTP/1.1 401 Unauthorized

{
  "error": "otp_expired",
  "message": "Your verification code has expired. Please request a new one."
}

HTTP/1.1 401 Unauthorized

{
  "error": "otp_invalid",
  "message": "Invalid verification code. Please try again."
}

HTTP/1.1 400 Bad Request
X-Fingerprint-Error: true

{
  "error": "FINGERPRINT_REQUIRED",
  "code": "FP001",
  "message": "Device fingerprint is required for this action",
  "support": {
    "message": "If you need assistance, please contact support with this reference code.",
    "referenceCode": "ABC123XYZ"
  }
}

HTTP/1.1 403 Forbidden
X-Fingerprint-Mismatch: true

{
  "valid": false,
  "error": "DEVICE_MISMATCH",
  "message": "This access token can only be used on the device that originally entered the queue.",
  "code": "FP002",
  "support": {
    "message": "If you need to switch devices, please contact support with your confirmation code.",
    "confirmationCode": "DEF456UVW"
  }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1701424860

{
  "error": "Rate limit exceeded",
  "retryAfter": 60
}

{
  "status": "DENIED",
  "denyReason": "ORDER_LIMIT_EXCEEDED",
  "consumerId": "cons_01HXYZ123456789"
}

const response = await fetch(url, options);

if (!response.ok) {
  const error = await response.json();
  // Handle based on status code
  switch (response.status) {
    case 400:
      handleValidationError(error);
      break;
    case 401:
      handleAuthError(error);
      break;
    case 429:
      handleRateLimitError(error, response.headers);
      break;
    default:
      handleGenericError(error);
  }
}

if (response.status === 429 || response.status === 423) {
  const retryAfter = response.headers.get("Retry-After");
  if (retryAfter) {
    // Could be seconds or ISO timestamp
    const delay = isNaN(retryAfter) ? new Date(retryAfter).getTime() - Date.now() : parseInt(retryAfter) * 1000;
    await sleep(delay);
    // Retry the request
  }
}

const errorMessages = {
  otp_expired: "Your code has expired. Please request a new one.",
  otp_invalid: "That code doesn't look right. Please check and try again.",
  DEVICE_MISMATCH: "Please use the same device you used to join the queue.",
  "Queue is full": "Sorry, this queue is currently full. Please try again later.",
};

console.error("API Error", {
  status: response.status,
  error: error.error,
  details: error.details,
  requestId: response.headers.get("X-Request-Id"),
  timestamp: new Date().toISOString(),
});

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      if (error.status >= 500) {
        await sleep(Math.pow(2, i) * 1000);
      } else {
        throw error; // Don't retry client errors
      }
    }
  }
}

async function apiCall(url, options) {
  const response = await fetch(url, options);

  if (response.status === 401) {
    const refreshed = await refreshToken();
    if (refreshed) {
      // Retry with new token
      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          Authorization: `Bearer ${refreshed.accessToken}`,
        },
      });
    }
  }

  return response;
}