API错误
https://litport.net/api/v1下的每个端点（令牌、套餐和按流量计费）都以本页所述的JSON格式返回错误。代理连接本身的故障使用单独的数字代理错误码，公开的免费代理API不在本页涵盖范围内。
错误格式#
{
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication failed.",
"requestId": "req_example",
"docsUrl": "https://litport.net/docs/api/errors"
}
}
相同的请求ID会出现在X-Request-ID响应头中。请将其与HTTP状态码和错误码一起记入日志。切勿记录Authorization请求头。
带有等待时间的409还会添加nextChangeAt，即ISO-8601 UTC时间戳：这是令牌位置或新IP上的CHANGE_LIMIT。
状态码参考#
| 状态码 | 错误码 | 客户端操作 |
|---|---|---|
400 |
INVALID, INVALID, INVALID, INVALID_TYPE, INVALID, INVALID, INVALID, INVALID, INVALID, INVALID_POOL, INVALID, INVALID, GEO, GEO, INVALID_IP, IPV6, INVALID, INVALID |
请修正请求。不要不加修改地重试。 |
401 |
UNAUTHORIZED |
请使用Bearer方案提供有效的 |
404 |
TOKEN, PACKAGE |
请检查ID和归属。响应不会泄露其 |
404 |
NOT_FOUND |
请修正路由；该路由不存在。 |
405 |
METHOD |
请使用Allow响应头中列出的方法之一。 |
409 |
NOT, PACKAGE, CONCURRENT, LOCATION, CHANGE_LIMIT, ALLOWED |
请参见下文相应的详细说明；CONCURRENT表示重试同一请求，CHANGE_LIMIT表示等到所报告的nextChangeAt。 |
413 |
INVALID |
请求体超过4 Ki |
415 |
INVALID |
对带请求体的写入，请发送Content-Type: application。 |
429 |
RATE_LIMITED |
请遵守Retry-After，并使用带随机抖动的退避。 |
503 |
SERVICE, TOKEN, ALLOWED |
请遵守Retry-After，使用有上限的退避重试，然后携带 |
重试算法#
对429和503按Retry-After并加入随机抖动自动重试，但POST /tokens/{tokenId}/new-ip上的503除外（见下文）。限制重试次数，并让调用方能够看到重试的总预算。
此API中除new-ip外的所有写入都可以安全重复：409 CONCURRENT_CHANGE或不明确的响应（超时、响应丢失、503）可以直接再次发送，因为最后一次写入始终生效，而且其他任何写入在已经应用的情况下都是空操作。对于new-ip，结果不明确时，应先读取GET /tokens/{tokenId}/location，仅当nextChangeAt不晚于当前时间时才重试。在一周内盲目重复只会返回409 CHANGE_LIMIT。
错误码详情#
无效的请求体#
请求体无法解析为JSON，或未通过端点自身的结构检查时返回400（例如，PUT /tokens/{tokenId}/rotation要求恰好为{"intervalSec": <integer>}）。请求体超过4 KiB时返回413。
无效的内容类型#
INVALID_CONTENT_TYPE表示发送带请求体的写入时没有带Content-Type: application/json。
无效的limit#
INVALID_LIMIT表示limit不是1到100（含）之间的整数。
无效的游标#
INVALID_CURSOR表示不透明游标格式错误、被修改过、无法通过验证，或是为其他端点签发的。请不带游标重新开始分页。
无效的类型#
INVALID_TYPE表示GET /tokens上的type不是unlimited或ppg。
无效的状态#
INVALID_STATUS表示GET /tokens上的status不是active、expired或disabled。
无效的套餐ID#
INVALID_PACKAGE_ID表示GET /tokens上的packageId筛选条件不是正整数。URL路径中的packageId永远不会返回400：未知或不属于当前用户的套餐ID返回404 PACKAGE_NOT_FOUND。
无效的时间范围#
INVALID_TIME_RANGE表示时间戳不是规范的UTC格式、from不早于to，或请求的时间跨度过大。
无效的分组方式#
INVALID_GROUP_BY表示groupBy不是hour、day或month。
无效的展开项#
INVALID_INCLUDE表示请求的展开项与令牌或分组不兼容；扣费明细需要PPG令牌和按小时的时间桶。
无效的代理池#
INVALID_POOL表示GET /pay-per-gb/geo上的pool缺失、为空，或包含的认证密钥无法对应到客户可选择的代理池。
无效的层级#
INVALID_LEVEL表示level不是该端点接受的值之一：令牌位置选项接受region/city，按流量计费的地理数据接受country/region/city。
无效的父级#
INVALID_PARENT表示缺少必需的上级地理信息：令牌的location/options?level=city需要region；GET /pay-per-gb/geo在level=region和level=city时都需要country。
未启用地理定位#
GEO_NOT_ENABLED表示所请求的代理池已关闭地理定位。
不支持的地理层级#
GEO_LEVEL_UNSUPPORTED表示所请求的代理池不支持所请求的level。请在按流量计费中查看该代理池的geoLevels。
无效的IP#
INVALID_IP表示提供的地址不是确切的公网IPv4字面地址。
不支持IPv6#
IPV6_UNSUPPORTED表示向套餐IP白名单写入发送了IPv6地址；请联系客服。
无效的位置#
INVALID_LOCATION表示所请求的州/省、城市或运营商不是此令牌可以使用的值，或country被设为"us"以外的值。
无效的轮换#
INVALID_ROTATION表示PUT /tokens/{tokenId}/rotation上的intervalSec不是该令牌所列options中的值。
未授权#
UNAUTHORIZED涵盖缺失、格式错误、未知、已轮换以及没有所属用户的密钥，且不会透露具体属于哪种情况。
未找到令牌#
TOKEN_NOT_FOUND涵盖任何令牌路由上缺失、不属于当前用户或无法解析的tokenId。所有情况下响应都相同，因此绝不会泄露其他用户的令牌。
未找到套餐#
PACKAGE_NOT_FOUND涵盖任何套餐路由（包括套餐的IP白名单）上缺失、不属于当前用户或无法解析的packageId。
未找到#
NOT_FOUND表示所请求的/api/v1路由不存在。
不允许的方法#
METHOD_NOT_ALLOWED表示已知端点收到了不受支持的方法。响应会在Allow中列出其支持的方法。
不支持#
NOT_SUPPORTED表示此令牌没有这项控制：其位置无法更改、其轮换间隔无法更改，或（new-ip）它不是静态数据中心或ISP代理。“多地点”令牌的轮换间隔始终返回NOT_SUPPORTED，因为它由代理所在的手机决定。
套餐未在使用中#
PACKAGE_INACTIVE表示令牌或套餐的付费周期当前未在使用中。
并发更改#
CONCURRENT_CHANGE表示对同一令牌或套餐的另一次写入恰好在同一时刻生效。请重试同一请求。
位置不可用#
LOCATION_UNAVAILABLE表示所请求的位置当前没有可用的IP或正常工作的设备。未发生任何更改。
更改次数限制#
CHANGE_LIMIT表示更改或更换的额度已用完：静态数据中心/ISP的新IP或位置更改每周一次，标准美国共享设备的位置更改每48小时一次。该错误会携带nextChangeAt和与之对应的Retry-After。
已达到IP白名单上限#
ALLOWED_IPS_LIMIT_REACHED表示套餐的IP白名单已达到其limit（1或50）。请联系客服提高上限。
触发速率限制#
RATE_LIMITED表示API密钥（对于IP白名单写入则是套餐）已用尽当前窗口的额度。请遵守Retry-After。
服务不可用#
SERVICE_UNAVAILABLE表示API所依赖的某项服务暂时不可用。请遵守Retry-After。
令牌数据无效#
TOKEN_DATA_INVALID表示令牌已保存的元数据暂时无法读取。请稍后重试，然后报告请求ID。
IP白名单不可用#
ALLOWED_IPS_UNAVAILABLE表示IP白名单的存储、配置或端口分配不可用，包括套餐暂时没有可分配的端口。
认证失败#
对于格式错误、未知、已轮换和没有所属用户的密钥，API有意返回相同的401响应格式。请在设置中创建或轮换API密钥。轮换会立即使之前有效的密钥失效。