如何处理接口错误

{
  "error": {
    "code": 12001,
    "type": "INSUFFICIENT_TOKENS",
    "message": "Token 额度不足，无法完成本次生成",
    "requestId": "req_abc123xyz",
    "details": {
      "field": "token_balance",
      "current": 0,
      "required": 500
    }
  }
}

async function requestWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 3
) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options)
 
      // 4xx 错误不重试——问题在请求本身
      if (response.status >= 400 && response.status < 500) {
        const error = await response.json()
        throw new ApiError(error)
      }
 
      // 5xx 错误可以重试——问题在服务端
      if (response.status >= 500 && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000 // 指数退避
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }
 
      return response
    } catch (error) {
      // 网络错误可以重试
      if (attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000
        await new Promise(resolve => setTimeout(resolve, delay))
        continue
      }
      throw error
    }
  }
}

// 统一的 API 错误处理层
async function handleApiError(error: unknown) {
  if (error instanceof ApiError) {
    switch (error.type) {
      case 'UNAUTHORIZED':
      case 'TOKEN_EXPIRED':
        // 尝试刷新 Token，失败则跳转登录
        await tryRefreshToken()
        break
 
      case 'RATE_LIMITED':
        // 从 Retry-After 头部获取等待时间
        const retryAfter = error.headers?.get('Retry-After') ?? '60'
        showToast(`请求过于频繁，请 ${retryAfter} 秒后重试`)
        break
 
      case 'INSUFFICIENT_TOKENS':
        // 引导到充值页面
        showUpgradeDialog('Token 额度不足，充值后即可继续使用')
        break
 
      case 'FORBIDDEN':
        showUpgradeDialog('此功能需要专业版计划')
        break
 
      case 'VALIDATION_ERROR':
        // 字段级错误交给表单组件展示
        return error.details
        break
 
      default:
        // 未预期的业务错误
        showToast(error.message ?? '操作失败，请稍后再试')
    }
  } else if (error instanceof NetworkError) {
    showToast('网络连接异常，请检查网络设置')
  } else {
    // 未知错误，上报到错误监控系统
    reportError(error)
    showToast('服务暂时不可用，请稍后再试')
  }
}

class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean; error: Error | null }
> {
  state = { hasError: false, error: null }
 
  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error }
  }
 
  componentDidCatch(error: Error, info: React.ErrorInfo) {
    // 上报到监控平台
    reportError(error, { componentStack: info.componentStack })
  }
 
  render() {
    if (this.state.hasError) {
      return <ErrorPage onRetry={() => this.setState({ hasError: false })} />
    }
    return this.props.children
  }
}

// 后端错误处理示例
async function handleGenerate(req: Request, res: Response) {
  const requestId = generateRequestId()
 
  try {
    // 1. 参数校验
    const { prompt, model } = req.body
    if (!prompt || prompt.length > 10000) {
      return res.status(422).json({
        error: {
          code: 10001,
          type: 'INVALID_PROMPT',
          message: 'Prompt 不能为空且长度不能超过 10000 字符',
          requestId,
        }
      })
    }
 
    // 2. 额度检查
    const balance = await getUserTokenBalance(req.userId)
    const required = estimateTokenCost(prompt)
    if (balance < required) {
      return res.status(422).json({
        error: {
          code: 12001,
          type: 'INSUFFICIENT_TOKENS',
          message: `Token 额度不足，当前 ${balance}，需要 ${required}`,
          requestId,
          details: { current: balance, required }
        }
      })
    }
 
    // 3. 调用 AI 模型（含重试逻辑）
    const result = await callModelWithRetry(model, prompt, {
      maxRetries: 2,
      fallbackModel: 'gpt-3.5-turbo'
    })
 
    // 4. 扣减额度
    await deductTokens(req.userId, result.tokensUsed)
 
    return res.json({ data: { content: result.content, tokensUsed: result.tokensUsed } })
 
  } catch (error) {
    // 5. 未预期异常
    logger.error('Generate failed', { requestId, userId: req.userId, error })
    return res.status(500).json({
      error: {
        code: 99001,
        type: 'INTERNAL_ERROR',
        message: '服务暂时不可用，请稍后再试',
        requestId
      }
    })
  }
}

async function generateContent(prompt: string) {
  try {
    const response = await fetch('/api/v1/generate', {
      method: 'POST',
      body: JSON.stringify({ prompt, model: 'gpt-4' })
    })
    const data = await response.json()
 
    if (!response.ok) {
      const { error } = data
      switch (error.type) {
        case 'INSUFFICIENT_TOKENS':
          showUpgradeDialog(`额度不足，当前 ${error.details.current}，需要 ${error.details.required}`)
          break
        case 'INVALID_PROMPT':
          // 字段级错误，展示在输入框下方
          setFieldError('prompt', error.message)
          break
        case 'RATE_LIMITED':
          showToast('操作太频繁，请稍后再试')
          break
        default:
          showToast(error.message)
      }
      return
    }
 
    // 成功
    setGeneratedContent(data.data.content)
  } catch (error) {
    showToast('网络连接异常，请检查网络后重试')
  }
}

{
  "error": {
    "code": 12001,
    "type": "INSUFFICIENT_TOKENS",
    "message": "Token 额度不足",
    "requestId": "req_xyz"
  }
}

// en.json
{
  "errors": {
    "INSUFFICIENT_TOKENS": "Insufficient token balance. Please top up to continue.",
    "INVALID_PROMPT": "Prompt cannot be empty or exceed 10,000 characters.",
    "RATE_LIMITED": "Too many requests. Please try again later."
  }
}

// ja.json
{
  "errors": {
    "INSUFFICIENT_TOKENS": "トークン残高が不足しています。チャージして続行してください。",
    "INVALID_PROMPT": "プロンプトは空または10,000文字を超えることはできません。",
    "RATE_LIMITED": "リクエストが多すぎます。後でもう一度お試しください。"
  }
}