{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-v2/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Errors & Rate Limits"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"errors--rate-limits","__idx":0},"children":["Errors & Rate Limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an API request fails, ShipSaving returns a structured error response with a machine-readable ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," and a human-friendly ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["msg"]},". This page documents the error response format, HTTP status codes and rate limits."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-response-format","__idx":1},"children":["Error Response Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All API responses — including errors — share the same JSON structure:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Success response:"]}]},{"$$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":["Error response:"]}]},{"$$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":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$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\""]}," on success; a dot-separated error code on failure (e.g. ",{"$$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":["A human-readable message describing the result."]}]},{"$$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":["The response payload on success; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," on failure."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"http-status-codes","__idx":2},"children":["HTTP Status Codes"]},{"$$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":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"When It Happens"},"children":["When It Happens"]}]}]},{"$$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":["Request succeeded. Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," field — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"ok\""]}," means success."]}]},{"$$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":["The request contains invalid parameters, missing required fields, or a business logic violation. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," field contains a specific error 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":["Access token is missing, expired, or invalid. Obtain a new token via ",{"$$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":["Too Many Requests"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You have exceeded the rate limit."]}]},{"$$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":["An unexpected error occurred on our side. If this persists, contact support."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-code-convention","__idx":3},"children":["Error Code Convention"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Error codes follow a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["dot-separated naming pattern"]}," that indicates the domain and specific issue:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{domain}.{subdomain}.{detail}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example:"]},{"$$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"]}," — Shipment domain → Address subdomain → City is missing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.transaction.wallet_balance_not_enough"]}," — Common domain → Transaction subdomain → Insufficient balance"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This pattern helps you programmatically categorize errors in your integration."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Exception"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," endpoint follows the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://datatracker.ietf.org/doc/html/rfc6749#section-5.2"},"children":["OAuth 2.0 error format"]}," and does not use the dot-separated convention above. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/v2/authentication"},"children":["Authentication"]}," for details."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"rate-limits","__idx":4},"children":["Rate Limits"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rate limits are applied at three levels:"]},{"$$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":"Level"},"children":["Level"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Scope"},"children":["Scope"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$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":["Per API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_key"]}," has its own allowance. One busy integration won't affect your other keys."]}]},{"$$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":["Per account"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All API keys under the same company share a combined limit, even if you use multiple keys."]}]},{"$$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":["Platform-wide"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A system-wide cap across all users. If the platform is under heavy load, requests may be rejected even if your key has room."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A request must pass all applicable levels. If any one of them is exceeded, the request is rejected."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Limits may vary"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Limits differ by endpoint and account tier, and may change over time. If you need higher throughput, contact your account manager."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you exceed the limit, the API returns HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," with error code ",{"$$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":"handling-recommendations","__idx":5},"children":["Handling Recommendations"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," field, not just HTTP status.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," response with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"code\": \"error\""]}," is still an error. Always check ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code == \"ok\""]}," before processing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Handle authentication errors gracefully.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"There are two types of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," errors:"]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Invalid credentials: If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"error\": \"invalid_client\"}"]},", your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_key"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_secret"]}," is incorrect. Double-check your credentials — do not retry."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Expired access token: If any other API endpoint returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," with an empty body, your access token has expired. Request a new token from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," and retry the original request."]}]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implement retry with backoff for transient errors.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"For errors like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.redis_lock.system_busy"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.pay.get_pay_lock_failed"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.check.rate_limit"]},", retry with exponential backoff:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Wait 1s → retry → wait 2s → retry → wait 4s → retry → give up\n"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do not retry validation errors.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Errors in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.address.*"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.package.*"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.custom.*"]}," categories indicate invalid input. Fix the request parameters before retrying."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform_uk_id"]}," to prevent duplicate shipments.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"If you receive a timeout or ambiguous response during label purchase, query the shipment status before retrying. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.current_platform_uk_id_already_create_shipment"]}," error protects against duplicate charges."]}]}]}]},"headings":[{"value":"Errors & Rate Limits","id":"errors--rate-limits","depth":2},{"value":"Error Response Format","id":"error-response-format","depth":3},{"value":"HTTP Status Codes","id":"http-status-codes","depth":3},{"value":"Error Code Convention","id":"error-code-convention","depth":3},{"value":"Rate Limits","id":"rate-limits","depth":3},{"value":"Handling Recommendations","id":"handling-recommendations","depth":3}],"frontmatter":{"seo":{"title":"Errors & Rate Limits"}},"lastModified":"2026-08-26T18:17:57.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/v2/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}