{"templateId":"markdown","versions":[{"version":"v5","label":"v5 (current)","link":"/errors-idempotency","default":true,"active":true,"folderId":"8a5edab2"},{"version":"v4","label":"v4","link":"/v4/errors-idempotency","default":false,"active":false,"folderId":"8a5edab2"},{"version":"v3","label":"v3 (legacy)","link":"/v3/errors-idempotency","default":false,"active":false,"folderId":"8a5edab2"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Errors & Idempotency","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"errors--idempotency","__idx":0},"children":["Errors & Idempotency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every v5 error response uses the same envelope:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": {\n    \"code\": \"validation_failed\",\n    \"message\": \"Human-readable summary.\",\n    \"details\": {\n      \"field\": [\"Per-field error message\"]\n    }\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The HTTP status gives the broad category. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]}," tells you what"," ","specifically happened. Branch on the code, not the message text."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-recovery-paths","__idx":1},"children":["Common recovery paths"]},{"$$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":"What to do"},"children":["What to do"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation_failed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]}," before retrying."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unauthenticated"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_expired"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token_revoked"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Issue or select a valid token."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scope_missing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Re-issue a token with the missing scope."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["insufficient_credits"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Top up credits before purchasing labels."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["too_many_requests"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with exponential backoff."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["conflict"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["*_in_use"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_voidable"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["not_cancellable"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inspect the resource state and retry only after it changes."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["internal_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry; contact support with the request ID if persistent."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi"},"children":["API Reference"]}," documents the full error vocabulary."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency-key","__idx":2},"children":["Idempotency-Key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every v5 endpoint that creates or charges accepts an optional"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header. Generate a unique value per logical operation and"," ","reuse the same key only when retrying the exact same request body."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"KEY=$(uuidgen)\ncurl -X POST \"$STALLION_BASE_URL/labels\" \\\n  -H \"Authorization: Bearer $STALLION_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $KEY\" \\\n  -d '{ ... }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Behavior:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Same key and same body within 24 hours returns the original response with"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotent-Replay: true"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Same key with a different body returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 idempotency_conflict"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," responses are not cached, so transient infrastructure failures can be"," ","retried with the same key."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this header for shipment creation, label purchase, pickups, LTL bookings,"," ","credit top-ups, product classification, and manufacturer verification."]}]},"headings":[{"value":"Errors & Idempotency","id":"errors--idempotency","depth":1},{"value":"Common recovery paths","id":"common-recovery-paths","depth":2},{"value":"Idempotency-Key","id":"idempotency-key","depth":2}],"frontmatter":{"seo":{"title":"Errors & Idempotency"}},"lastModified":"2026-06-11T19:50:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/errors-idempotency","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}