API 错误代码说明

我们的API使用标准的HTTP状态码来指示API请求的成功或失败。通常来说：

2xx范围的状态码表示成功。

4xx范围的状态码表示客户端错误（例如，请求参数错误、认证失败等）。

5xx范围的状态码表示服务器端错误。

当API请求发生错误时，除了HTTP状态码，响应体（通常为JSON格式）会包含更详细的错误信息，帮助您定位和解决问题。一个典型的错误响应体可能如下所示：

{
  "error": {
    "type": "authentication_error", // 错误类型
    "message": "提供的API密钥不正确。", // 人类可读的错误信息
    "code": "invalid_api_key",      // (option) 更细粒度的程序化错误码
    "param": null                   // (option) 指示哪个参数有问题
  }
}

`400 Bad Request` - 请求错误

HTTP 400 Bad Request 状态码表示服务器因认为客户端错误（例如，请求语法格式错误、无效的请求消息帧，或欺骗性的请求路由）而无法或不会处理该请求。

error_type: request_error

概述： 您发送到API的请求在结构、格式或内容上存在问题，导致服务器无法理解或处理它。这通常不是服务器端的问题，而是客户端构造请求的方式有误。

internal_code: invalid_request (或者更具体的，如 malformed_json, missing_required_parameter, invalid_parameter_value)

可能原因：

请求体格式错误： 例如，发送的JSON格式不正确（如括号不匹配、缺少逗号、无效的JSON结构）。

缺少必需参数： API端点要求的某些必需参数没有在请求中提供。

参数值无效： 提供的参数值不符合预期的类型、格式或范围（例如，期望一个整数却收到了字符串，日期格式错误，枚举值无效）。

请求头不正确或缺失： 例如，Content-Type 请求头与实际发送的请求体不匹配，或者缺少必要的认证头信息（尽管 401 更常用于认证问题，但有时格式错误的认证头也可能导致 400）。

请求过大： 请求体的大小超过了服务器允许的最大限制。

无效的请求路径或查询参数： URL本身可能包含无效字符或不被支持的查询参数。

建议操作：

仔细检查您的请求体：

如果发送的是JSON，请使用JSON验证工具（linter/validator）检查其语法是否正确。

确保所有字段名和数据类型与API文档中定义的一致。

核对API文档：

确认所有必需的参数都已包含在请求中。

检查每个参数的值是否符合API文档中规定的格式、数据类型和约束（如最大长度、允许的值范围等）。

检查请求头： 确保 Content-Type 与您发送的数据格式相符（例如，application/json 用于JSON数据）。

查看响应体中的详细错误信息： 我们的API通常会在 400 错误的响应体中提供更具体的错误细节，指出是哪个字段或哪个方面出了问题。例如：

{
  "error": {
    "type": "validation_error",
    "message": "Invalid value for parameter 'age'. Expected an integer.",
    "code": "invalid_parameter_value",
    "param": "age" // 指示哪个参数有问题
  }
}

如果问题持续存在且您已仔细检查过上述各项，请联系技术支持，并提供完整的请求（包括头部和主体）以及收到的响应。

`401 Unauthorized` - 认证失败

HTTP 401 Unauthorized 状态码表示请求由于缺乏有效的身份验证凭据而应用失败。

error_type: authentication_error

1. 认证信息无效或权限不足

概述： 提供的身份验证凭据（如API密钥）虽然可能存在，但由于某些原因（如已被吊销、过期或不具备执行所请求操作的权限）导致认证失败。

internal_code: authentication_failed

可能原因：

您使用的API密钥已被吊销或停用。

您使用的API密钥不具备访问所请求资源或执行所请求操作的必要权限。

您的账户状态异常（例如被临时冻结）。

建议操作：

请检查您的API密钥是否为最新且有效。

确认您的API密钥拥有正确的权限范围来执行当前操作。

检查您的账户状态，确保服务正常。

如果问题持续，请联系技术支持并提供请求ID以便我们排查。

2. 提供的API密钥不正确

概述： 请求中提供的API密钥本身是错误的，例如格式不正确、不存在，或者是一个已被明确禁用的密钥。

internal_code: invalid_api_key

可能原因：

您在请求中传入的API密钥字符串不正确（例如，拼写错误、复制不完整）。

您使用的API密钥不存在于我们的系统中。

您尝试使用的API密钥已被永久禁用。

建议操作：

请仔细核对您使用的API密钥，确保其准确无误。

如果您不确定API密钥的正确性，请考虑在您的账户控制面板中重新生成一个新的API密钥。

清除浏览器缓存或任何可能缓存了旧密钥的中间层。

`403 Forbidden` - 禁止访问

HTTP 403 Forbidden 状态码表示服务器理解请求客户端的请求，但是拒绝执行此请求。与 401 Unauthorized 不同，身份验证通常不是问题，而是客户端没有访问该资源的权限。

error_type: permission_error

概述： 即使身份验证成功，您也无权访问所请求的特定资源或执行特定操作。

internal_code: permission_denied

可能原因：

您的账户余额不足。

您的账户或API密钥没有被授予访问此特定端点或资源的权限。

您尝试访问一个仅限特定用户组或角色的资源。

建议操作：

请确保您的账户余额充足且没有欠费。

请查阅API文档，确认您所请求的资源或操作的访问条件。

检查您的账户设置或API密钥配置，确保已启用相关权限。

如果认为配置无误但仍遇到此问题，请联系技术支持。

`429 Too Many Requests` - 请求过于频繁

HTTP 429 Too Many Requests 状态码表示用户在给定的时间内发送了太多的请求（即“速率限制”）。

error_type: limit_error

1. TPM (Tokens Per Minute) 限制超出

概述： 您在单位时间内（通常是一分钟）请求处理的令牌（Tokens）总数超过了您的账户套餐所允许的上限。

internal_code: tpm_limit_exceeded

可能原因：

您的请求包含了大量需要处理的文本或数据，导致消耗的令牌数迅速增加。

您正在使用循环或脚本，在短时间内并发或连续地提交了大量消耗令牌的请求。

您正在与其他用户或应用程序共享您的API密钥，导致总令牌消耗量超出限制。

您当前使用的是速率限制较低的免费套餐或低级别套餐。

建议操作：

优化您的请求，减少单次请求处理的令牌数量（例如，缩短文本长度）。

在您的应用程序中实施退避策略（Exponential Backoff），在收到 429 错误后逐渐增加重试间隔。

检查是否有其他应用或脚本正在使用同一API密钥。

考虑升级您的账户套餐以获取更高的TPM限制。

查阅API文档中的速率限制指南。

2. RPM (Requests Per Minute) 限制超出

概述： 您在单位时间内（通常是一分钟）发送的API请求总次数超过了您的账户套餐所允许的上限。

internal_code: rpm_limit_exceeded

可能原因：

您的应用程序在短时间内发送了过多的API调用，即使每次调用的令牌消耗量不高。

您正在使用循环或脚本，过于频繁地轮询API。

您正在与其他用户或应用程序共享您的API密钥，导致总请求数超出限制。

建议操作：

降低您的请求频率。检查您的代码，确保没有不必要的或过于频繁的API调用。

在您的应用程序中实施退避策略（Exponential Backoff）。

如果需要高频率请求，考虑升级您的账户套餐以获取更高的RPM限制。

查阅API文档中的速率限制指南。

`500 Internal Server Error` - 服务器内部错误

HTTP 500 Internal Server Error 状态码表示服务器在处理请求时遇到了一个意外情况，导致无法完成请求。

error_type: internal_server_error

概述： 这是服务器端发生的通用错误，表明我们的服务器在尝试处理您的请求时遇到了问题。

internal_code: internal_server_error

可能原因：

我们的服务器遇到了一个未预料到的临时性问题或bug。

请求可能格式正确，但在服务器处理过程中触发了内部异常。

建议操作：

请短暂等待（例如，几秒到一分钟）后重试您的请求。这类问题通常是暂时的。

如果多次重试后问题仍然存在，请联系技术支持，并提供尽可能详细的请求信息（如请求ID、时间、请求内容摘要）以便我们诊断。

`503 Service Unavailable` - 服务不可用

HTTP 503 Service Unavailable 状态码表示服务器当前无法处理请求，通常是由于服务器过载或正在进行维护。

error_type: server_resource_error

概述： 我们的服务器暂时无法处理您的请求，这通常是由于临时过载或计划维护。

internal_code: service_unavailable (或更具体的如 server_overloaded, maintenance_mode)

可能原因：

我们的服务器当前正承受非常高的流量，导致处理能力饱和。

我们的服务器可能正在进行计划内或计划外的维护或更新。

发生了意外或不可避免的基础设施中断或事件。

您的请求速率在短时间内突然大幅增加，影响了服务的稳定性。

建议操作：

请在短暂等待后（例如，几秒到几分钟）重试您的请求。建议使用带退避策略的重试机制。

如果错误信息指示您“减速”（Slow Down），请立即降低您的请求速率至正常水平，并保持至少15分钟，然后尝试逐渐增加。

如果在合理的时间（例如，几分钟到几十分钟）后仍然持续遇到此错误，请联系我们寻求进一步帮助。

400 Bad Request - 请求错误#

401 Unauthorized - 认证失败#

1. 认证信息无效或权限不足#

2. 提供的API密钥不正确#

403 Forbidden - 禁止访问#

429 Too Many Requests - 请求过于频繁#

1. TPM (Tokens Per Minute) 限制超出#

2. RPM (Requests Per Minute) 限制超出#

500 Internal Server Error - 服务器内部错误#

503 Service Unavailable - 服务不可用#

`400 Bad Request` - 请求错误

`401 Unauthorized` - 认证失败

1. 认证信息无效或权限不足

2. 提供的API密钥不正确

`403 Forbidden` - 禁止访问

`429 Too Many Requests` - 请求过于频繁

1. TPM (Tokens Per Minute) 限制超出

2. RPM (Requests Per Minute) 限制超出

`500 Internal Server Error` - 服务器内部错误

`503 Service Unavailable` - 服务不可用