Realm API 文档

Appearance

常见错误码说明 ​

本文档详细说明了 RealmRouter API 调用过程中可能遇到的错误码、错误原因以及相应的解决方案，帮助开发者快速定位和解决问题。

错误响应格式 ​

所有 API 错误响应都遵循统一的格式：

json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided",
    "type": "authentication_error",
    "param": "authorization",
    "timestamp": "2024-01-01T12:00:00Z",
    "request_id": "req_123456789"
  }
}

字段说明 ​

  • code: 错误代码，用于程序化处理
  • message: 错误描述，便于人工理解
  • type: 错误类型，用于分类处理
  • param: 相关参数，指示错误来源
  • timestamp: 错误发生时间
  • request_id: 请求唯一标识，用于问题追踪

认证错误 (4xx) ​

401 Unauthorized ​

invalid_api_key ​

  • 错误码: invalid_api_key
  • 错误信息: "Invalid API key provided"
  • 原因: API 密钥无效、格式错误或不存在
  • 解决方案:
    1. 检查 API 密钥是否正确
    2. 确认密钥格式（应为 "sk-" 开头）
    3. 验证密钥是否已激活
    4. 重新生成 API 密钥

api_key_expired ​

  • 错误码: api_key_expired
  • 错误信息: "API key has expired"
  • 原因: API 密钥已过期
  • 解决方案:
    1. 检查密钥有效期
    2. 重新生成新的 API 密钥
    3. 更新应用中的密钥配置

insufficient_permissions ​

  • 错误码: insufficient_permissions
  • 错误信息: "Insufficient permissions for this operation"
  • 原因: 当前密钥权限不足
  • 解决方案:
    1. 检查密钥权限范围
    2. 联系管理员提升权限
    3. 使用具有足够权限的密钥

403 Forbidden ​

account_suspended ​

  • 错误码: account_suspended
  • 错误信息: "Account has been suspended"
  • 原因: 账户被暂停使用
  • 解决方案:
    1. 检查账户状态
    2. 联系客服了解原因
    3. 处理违规问题后申请恢复

rate_limit_exceeded ​

  • 错误码: rate_limit_exceeded
  • 错误信息: "Rate limit exceeded"
  • 原因: 超出调用频率限制
  • 解决方案:
    1. 降低请求频率
    2. 实现指数退避重试
    3. 升级到更高套餐
    4. 使用请求队列

quota_exceeded ​

  • 错误码: quota_exceeded
  • 错误信息: "Quota exceeded"
  • 原因: 超出使用配额
  • 解决方案:
    1. 检查当前配额使用情况
    2. 等待配额重置（通常按月重置）
    3. 升级套餐增加配额
    4. 购买额外配额包

请求错误 (4xx) ​

400 Bad Request ​

invalid_request ​

  • 错误码: invalid_request
  • 错误信息: "Invalid request format"
  • 原因: 请求格式不正确
  • 解决方案:
    1. 检查 JSON 格式是否正确
    2. 验证必需参数是否完整
    3. 确认参数类型和格式
    4. 参考 API 文档检查请求结构

invalid_model ​

  • 错误码: invalid_model
  • 错误信息: "Invalid model specified"
  • 原因: 指定的模型不存在或不可用
  • 解决方案:
    1. 检查模型名称拼写
    2. 确认模型是否可用
    3. 查看支持的模型列表
    4. 使用正确的模型标识符

invalid_parameters ​

  • 错误码: invalid_parameters
  • 错误信息: "Invalid parameters provided"
  • 原因: 参数值无效或超出范围
  • 解决方案:
    1. 检查参数值范围
    2. 验证参数类型
    3. 确认必需参数
    4. 参考参数说明文档

context_length_exceeded ​

  • 错误码: context_length_exceeded
  • 错误信息: "Context length exceeded"
  • 原因: 输入内容超出模型上下文长度限制
  • 解决方案:
    1. 减少输入内容长度
    2. 使用支持更长上下文的模型
    3. 实现文本分割策略
    4. 移除不必要的上下文

408 Request Timeout ​

request_timeout ​

  • 错误码: request_timeout
  • 错误信息: "Request timeout"
  • 原因: 请求处理超时
  • 解决方案:
    1. 减少请求复杂度
    2. 降低 max_tokens 参数
    3. 使用流式输出
    4. 增加客户端超时时间

服务器错误 (5xx) ​

500 Internal Server Error ​

internal_error ​

  • 错误码: internal_error
  • 错误信息: "Internal server error"
  • 原因: 服务器内部错误
  • 解决方案:
    1. 稍后重试请求
    2. 检查服务状态页面
    3. 联系技术支持
    4. 提交错误报告

model_overloaded ​

  • 错误码: model_overloaded
  • 错误信息: "Model is currently overloaded"
  • 原因: 模型服务负载过高
  • 解决方案:
    1. 等待一段时间后重试
    2. 使用其他可用模型
    3. 降低请求频率
    4. 联系客服了解恢复时间

503 Service Unavailable ​

service_unavailable ​

  • 错误码: service_unavailable
  • 错误信息: "Service temporarily unavailable"
  • 原因: 服务暂时不可用
  • 解决方案:
    1. 检查服务状态公告
    2. 等待服务恢复
    3. 使用备用服务
    4. 订阅服务状态通知

maintenance_mode ​

  • 错误码: maintenance_mode
  • 错误信息: "Service under maintenance"
  • 原因: 服务维护中
  • 解决方案:
    1. 查看维护公告
    2. 等待维护完成
    3. 调整使用计划
    4. 提前安排重要任务

内容错误 (4xx) ​

400 Bad Request ​

content_filtered ​

  • 错误码: content_filtered
  • 错误信息: "Content filtered by safety policy"
  • 原因: 内容违反安全策略
  • 解决方案:
    1. 检查输入内容
    2. 修改或删除敏感内容
    3. 使用更中性的表达
    4. 了解内容政策

inappropriate_content ​

  • 错误码: inappropriate_content
  • 错误信息: "Inappropriate content detected"
  • 原因: 检测到不当内容
  • 解决方案:
    1. 修改输入内容
    2. 避免敏感话题
    3. 使用内容预检查
    4. 了解使用条款

错误处理最佳实践 ​

1. 错误重试策略 ​

python
import time
import random
from requests.exceptions import RequestException

def api_call_with_retry(url, headers, data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, json=data, timeout=30)
            
            if response.status_code == 200:
                return response.json()
            elif response.status_code == 429:
                # 速率限制，指数退避
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(wait_time)
                continue
            elif response.status_code >= 500:
                # 服务器错误，重试
                if attempt < max_retries - 1:
                    time.sleep(1)
                    continue
                else:
                    raise Exception("Server error after retries")
            else:
                # 客户端错误，不重试
                response.raise_for_status()
                
        except RequestException as e:
            if attempt == max_retries - 1:
                raise e
            time.sleep(1)
    
    raise Exception("API call failed after retries")

2. 错误日志记录 ​

python
import logging
import json

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def log_api_error(response):
    try:
        error_data = response.json()
        error_info = {
            'status_code': response.status_code,
            'error_code': error_data.get('error', {}).get('code'),
            'error_message': error_data.get('error', {}).get('message'),
            'error_type': error_data.get('error', {}).get('type'),
            'request_id': error_data.get('error', {}).get('request_id'),
            'timestamp': error_data.get('error', {}).get('timestamp')
        }
        logger.error(f"API Error: {json.dumps(error_info, indent=2)}")
    except:
        logger.error(f"API Error: HTTP {response.status_code} - {response.text}")

3. 错误分类处理 ​

python
def handle_api_error(response):
    if response.status_code == 401:
        # 认证错误
        raise AuthenticationError("Invalid API key or permissions")
    elif response.status_code == 429:
        # 速率限制
        raise RateLimitError("Rate limit exceeded")
    elif response.status_code == 400:
        # 请求错误
        error_data = response.json()
        error_code = error_data.get('error', {}).get('code')
        if error_code == 'context_length_exceeded':
            raise ContextLengthError("Input too long")
        elif error_code == 'invalid_model':
            raise InvalidModelError("Model not available")
        else:
            raise InvalidRequestError("Invalid request")
    elif response.status_code >= 500:
        # 服务器错误
        raise ServerError("Server error occurred")
    else:
        # 其他错误
        raise APIError(f"API error: {response.status_code}")

监控和告警 ​

1. 错误率监控 ​

  • 设置错误率阈值告警
  • 监控不同类型错误的分布
  • 跟踪错误趋势变化

2. 性能监控 ​

  • 监控响应时间
  • 跟踪成功率变化
  • 监控服务可用性

3. 业务监控 ​

  • 监控 API 调用量
  • 跟踪用户行为
  • 监控成本变化

获取帮助

如果遇到无法解决的错误：

  1. 查看错误码对应的解决方案
  2. 检查服务状态页面
  3. 搜索开发者社区
  4. 提交技术支持工单
  5. 联系客户经理

基于 MIT 许可发布 厦门界云聚算网络科技有限公司

Copyright © 2025 Realm API