API错误

https://litport.net/api/v1下的每个端点（令牌及用量、套餐和按流量计费）都以本页所述的JSON格式返回错误。代理连接本身的故障使用单独的数字代理错误码，公开的免费代理API不在本页涵盖范围内。

错误格式#

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication failed.",
    "requestId": "req_example",
    "docsUrl": "https://litport.net/docs/api/errors",
    "retryable": false
  }
}

相同的请求ID会出现在X-Request-ID响应头中。请将其与HTTP状态码和错误码一起记入日志。切勿记录Authorization请求头。

带有等待时间的409还会添加nextChangeAt，即ISO-8601 UTC时间戳：这是令牌位置或新IP上的CHANGE_LIMIT。

retryable始终存在，取值为true或false。true表示同一请求在Retry-After（或错误中带有nextChangeAt时，在该时间）之后原样再次发送，可能成功，并且可以安全地再次发送：要么什么都没有做（RATE_LIMITED、CONCURRENT_CHANGE、CHANGE_LIMIT、ALLOWANCE_CONFLICT），要么是对可以安全重复的请求返回的503。false表示需要先做出更改：请求、账户或令牌。对不能安全重复的请求返回的503同样是false：先读取当前状态再决定（见重试算法）。

状态码参考#

重试算法#

仅当retryable为true时才自动重试：等待Retry-After（错误带有nextChangeAt时，还要等到该时间），加入随机抖动，然后再次发送同一请求。限制重试次数，并让调用方能够看到重试的总预算。当retryable为false时，应先做出更改；或者，对不能安全重复的请求出现不明确的失败后（见下文），先读取当前状态再决定。

此API中除new-ip、POST /tokens（不带externalRef）、POST /tokens/{tokenId}/credentials（不带requestId）、PUT /tokens/{tokenId}/location（带{"random": true}）以及支持API的两个POST（POST /support/conversations和POST /support/conversations/{conversationId}/messages）外的所有写入都可以安全重复。任何其他收到409 CONCURRENT_CHANGE或不明确响应（超时、响应丢失、503）的写入都可以直接再次发送，因为最后一次写入始终生效，而且其他任何写入在已经应用的情况下都是空操作。对不能安全重复的请求，503会带有retryable: false，因为在失败之前工作可能已经完成。

对于静态令牌的new-ip，结果不明确时，应先读取GET /tokens/{tokenId}/location，仅当nextChangeAt不晚于当前时间时才重试。在一周内盲目重复只会返回409 CHANGE_LIMIT。

带有externalRef的创建可以安全重复：重复请求会返回已存在的代理。没有它，重复请求可能创建出第二个代理。带有requestId的重新签发可以安全重复：重复请求会返回第一次调用签发的凭证。没有它，重复请求会再签发一组新的凭证。见创建和管理代理。

对动态令牌来说，new-ip无法通过GET /tokens/{tokenId}/location确认：其canChangeNow和nextChangeAt针对的是位置，与新IP之间的等待期无关。在Retry-After之后再次发送没有影响，只会再给一个新IP。响应丢失后立刻收到409 CHANGE_LIMIT，并不能证明更改已生效，因为409 LOCATION_UNAVAILABLE的响应同样会占用等待期。

带{"random": true}的PUT /tokens/{tokenId}/location每次都会选择一个新位置，因此在没有等待期的情况下，重复发送会再次移动代理。响应丢失后，先读取GET /tokens/{tokenId}/location，仅当代理不在你想要的位置时才再次发送。支持API的两个POST没有幂等键，而且503可能在消息已保存之后才出现：再次发送消息之前，请先读取对话。

错误码详情#

无效的请求体#

请求体无法解析为JSON，或未通过端点自身的结构检查时返回400（例如，PUT /tokens/{tokenId}/rotation要求恰好为{"intervalSec": <integer>}）。在POST /tokens、PATCH /tokens/{tokenId}和POST /tokens/{tokenId}/credentials上，请求体必须是只包含该调用所接受字段的JSON对象，而PATCH至少需要一个字段。请求体超过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_TOKEN_IDS表示GET /usage上的tokenIds不是正整数的代理ID列表，或列出的ID超过100个。

无效的套餐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、POST /tokens或PATCH /tokens/{tokenId}上的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中的值。

无效的标签#

INVALID_LABEL表示label不是最多255个字符的文本，也不是用于清除标签的null。

无效的外部引用#

INVALID_EXTERNAL_REF表示externalRef不是1到128个可打印字符。

无效的请求ID#

INVALID_REQUEST_ID表示POST /tokens/{tokenId}/credentials上的requestId不是1到64个字符，由字母、数字、下划线或连字符组成。

无效的启用开关#

INVALID_ENABLED表示enabled不是true或false。

无效的到期时间#

INVALID_EXPIRY表示expiresAt不是尚未到来的、带时区的ISO 8601日期时间或日期，也不是null。

无效的流量上限#

INVALID_ALLOWANCE表示allowanceBytes不是至少为1（字节）的整数，也不是用于取消上限的null。

不允许的字段#

FIELD_NOT_ALLOWED表示PATCH /tokens/{tokenId}向套餐的代理发送了label以外的字段。套餐的代理由其套餐启用和停用。

未授权#

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，因为它由代理所在的手机决定。套餐代理上的DELETE /tokens/{tokenId}同样返回它：只有按流量计费的代理可以删除。

余额不足#

INSUFFICIENT_BALANCE为402。创建代理和启用代理需要正数余额。其他操作在余额为空时都能进行：停用、更改标签、更改到期时间或流量上限、重新签发凭证以及删除。

账户被封禁#

ACCOUNT_BANNED为403。被封禁的账户不能创建代理或启用代理。停用、重新签发凭证和删除仍然可用。请联系客服。

已达到令牌数量上限#

TOKEN_LIMIT_REACHED表示账户已持有允许的最大数量的按流量计费代理。请删除不再使用的代理，或联系客服提高上限。

令牌无法编辑#

TOKEN_NOT_EDITABLE表示该代理已无法再编辑，例如因为写入进行期间它被删除了。未发生任何更改。请读取该代理以查看其当前状态。

流量上限冲突#

ALLOWANCE_CONFLICT表示流量上限未能保存。未发生任何更改。请再次发送同一请求。

IP白名单登录需要代理池#

POOL_REQUIRED_FOR_IP_AUTH表示对一个通过IP白名单登录的代理发送了pool: null。该代理需保留一个代理池。

套餐未在使用中#

PACKAGE_INACTIVE表示令牌或套餐的付费周期当前未在使用中。

并发更改#

CONCURRENT_CHANGE表示对同一令牌或套餐的另一次写入恰好在同一时刻生效。请重试同一请求。

位置不可用#

LOCATION_UNAVAILABLE表示所请求的位置当前没有可用的IP或正常工作的设备。未发生任何更改。

不处于fallback状态#

NOT_IN_FALLBACK是POST /tokens/{tokenId}/location/return在令牌并未处于其已保存位置之外时的响应，因此无需移回。对已成功的请求再次发送会到这里，且不会再给第二个IP。未发生任何更改。

更改次数限制#

CHANGE_LIMIT表示更改或更换的额度已用完：静态数据中心/ISP的新IP或位置更改每周一次，标准美国共享设备的位置更改每48小时一次。动态数据中心/ISP令牌获取新IP时，等待期为令牌rotation.options中的最小值，从上一次请求起算。该错误会携带nextChangeAt和与之对应的Retry-After。

已达到IP白名单上限#

ALLOWED_IPS_LIMIT_REACHED表示套餐的IP白名单已达到其limit（1或50）。请联系客服提高上限。

触发速率限制#

RATE_LIMITED表示API密钥（对于GET /usage，是它自己的每60秒10次请求的限制）、对于IP白名单写入是套餐、对于POST /tokens是账户（它每分钟创建新代理的限制，由其所有密钥和控制台共用）已用尽当前窗口的额度。未执行任何操作。请遵守Retry-After；retryable为true。

服务不可用#

SERVICE_UNAVAILABLE表示API所依赖的某项服务暂时不可用。请遵守Retry-After。当请求不能安全重复时，retryable为false；见重试算法。

令牌数据无效#

TOKEN_DATA_INVALID表示令牌已保存的元数据暂时无法读取。请稍后重试，然后报告请求ID。

IP白名单不可用#

ALLOWED_IPS_UNAVAILABLE表示IP白名单的存储、配置或端口分配不可用，包括套餐暂时没有可分配的端口。

认证失败#

对于格式错误、未知、已轮换和没有所属用户的密钥，API有意返回相同的401响应格式。请在设置中创建或轮换API密钥。轮换会立即使之前有效的密钥失效。