{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/zh-Hans/v2/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"错误与限流"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"错误与限流","__idx":0},"children":["错误与限流"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["当 API 请求失败时，ShipSaving 会返回结构化的错误响应，包含机器可读的 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," 和人类可读的 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["msg"]},"。本页说明错误响应格式、HTTP 状态码、限流机制。"]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"错误响应格式","__idx":1},"children":["错误响应格式"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["所有 API 响应（包括错误）都使用相同的 JSON 结构："]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["成功响应："]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"ok\",\n  \"msg\": \"ok\",\n  \"data\": { ... }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["错误响应："]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"shipment.address.city_can_not_be_null\",\n  \"msg\": \"City is required.\",\n  \"data\": null\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"字段"},"children":["字段"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"类型"},"children":["类型"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"说明"},"children":["说明"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["成功时为 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"ok\""]},"；失败时为以点分隔的错误码（如 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.buy.pay_shipment_failed"]},"）。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["msg"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["描述结果的可读消息。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object / null"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["成功时包含响应数据；失败时为 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"。"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"http-状态码","__idx":2},"children":["HTTP 状态码"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"状态码"},"children":["状态码"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"含义"},"children":["含义"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"触发场景"},"children":["触发场景"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OK"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["请求成功。注意仍需检查 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," 字段，",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"ok\""]}," 才表示真正成功。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bad Request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["请求参数无效、缺少必填字段或违反业务规则。",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," 字段包含具体的错误码。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unauthorized"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["访问令牌缺失、过期或无效。需通过 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," 重新获取令牌。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["请求过于频繁"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["您的请求频率超过了限流阈值。请降低调用速率后重试。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Internal Server Error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["服务端发生意外错误。如果持续出现，请联系技术支持。"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"错误码命名规则","__idx":3},"children":["错误码命名规则"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["错误码采用",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["点分隔命名"]},"，标识所属的业务域和具体问题："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{domain}.{subdomain}.{detail}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["示例："]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.address.city_can_not_be_null"]}," — 运单域 → 地址子域 → 城市缺失"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.transaction.wallet_balance_not_enough"]}," — 通用域 → 交易子域 → 余额不足"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["你可以利用域名前缀在代码中对错误进行分类处理（例如，所有 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.address.*"]}," 错误表示地址输入有误）。"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"例外"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," 接口遵循 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://datatracker.ietf.org/doc/html/rfc6749#section-5.2"},"children":["OAuth 2.0 错误格式"]},"，不使用上述点分隔命名规则。详见",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/zh-hans/v2/authentication"},"children":["认证"]},"。"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"限流","__idx":4},"children":["限流"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["限流在三个层级生效："]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"层级"},"children":["层级"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"范围"},"children":["范围"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"说明"},"children":["说明"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["App Key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["单个 API Key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["每个 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_key"]}," 有独立的请求配额。某个集成的高频调用不会影响你的其他 Key。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Company"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["单个账户"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["同一公司下的所有 API Key 共享一个配额，即使使用多个 Key 也会合并计算。"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Global"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["全平台"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["全平台的总请求上限。当平台整体负载较高时，即使你的 Key 还有余量，请求也可能被拒绝。"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["一个请求必须通过所有适用层级的检查。任何一个层级超限，请求都会被拒绝。"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"限额说明"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["限额因接口和账户等级而异，且可能随时调整。如果你的集成需要更高的吞吐量，请联系你的客户经理。"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["当超出限流时，API 返回 HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]},"，错误码为 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.check.rate_limit"]},"："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"common.check.rate_limit\",\n  \"msg\": \"request too frequent\",\n  \"data\": null\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"处理建议","__idx":5},"children":["处理建议"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["检查 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," 字段，而非仅依赖 HTTP 状态码。",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," 响应中 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"code\": \"error\""]}," 仍然是错误。务必在处理 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," 之前确认 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code == \"ok\""]},"。"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["自动处理认证错误。",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," 错误分为两种情况："]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["凭证错误：如果 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," 返回 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," 且响应体为 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"error\": \"invalid_client\"}"]},"，说明 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_key"]}," 或 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_secret"]}," 不正确。请检查凭证，不要重试。"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["访问令牌过期：如果其他 API 接口返回 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," 且响应体为空，说明访问令牌已失效。请通过 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," 重新获取令牌后重试原始请求。"]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["对瞬态错误实施退避重试。",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"遇到 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.redis_lock.system_busy"]},"、",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.pay.get_pay_lock_failed"]}," 或 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.check.rate_limit"]}," 等错误时，使用指数退避策略重试："]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"等待 1s → 重试 → 等待 2s → 重试 → 等待 4s → 重试 → 放弃\n"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["不要重试校验类错误。",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.address.*"]},"、",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.package.*"]},"、",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.custom.*"]}," 类别的错误表示输入有误，需修正请求参数后再重试。"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["使用 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform_uk_id"]}," 防止重复下单。",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"如果在购买面单时遇到超时或不明确的响应，先查询运单状态再决定是否重试。",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.current_platform_uk_id_already_create_shipment"]}," 错误可以防止重复扣费。"]}]}]}]},"headings":[{"value":"错误与限流","id":"错误与限流","depth":2},{"value":"错误响应格式","id":"错误响应格式","depth":3},{"value":"HTTP 状态码","id":"http-状态码","depth":3},{"value":"错误码命名规则","id":"错误码命名规则","depth":3},{"value":"限流","id":"限流","depth":3},{"value":"处理建议","id":"处理建议","depth":3}],"frontmatter":{"seo":{"title":"错误与限流"}},"lastModified":"2026-08-26T18:17:57.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/zh-hans/v2/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}