snapcasterAPI reference
Error codes
The partner API returns every error in one of two bodies.
Read code from where the body’s shape puts it, and branch on that stable code, not on the human-readable message, which may change.
Retries says which failures to retry and how.
| Body | code location | Used for |
|---|---|---|
{ "success": false, "error": { "code", "message", "details?" } } | error.code | Every error an operation answers itself, including 400, 401, 403, 404, 409, 422, 429, and the batch-size 413 BATCH_TOO_LARGE |
{ "status": "error", "message", "code" } | code | 500 INTERNAL_ERROR, 413 PAYLOAD_TOO_LARGE for a body larger than the operation accepts, 404 NOT_FOUND for a path or method that no operation serves, and 400 INVALID_REQUEST for a body that is not valid JSON sent to an operation that takes no body or to a path that no operation serves |
A request body that is not valid JSON, a path segment that is not valid percent-encoding, and a missing required body each return the operation’s HTTP 400 INVALID_REQUEST in the first body.
Snapcaster checks the marketplace API key before it reads the body, so an invalid key returns 401 UNAUTHORIZED first, except in the second body’s PAYLOAD_TOO_LARGE and INVALID_REQUEST cases, which come before the key check.
Request failures
| HTTP | Code | Meaning | Do this |
|---|---|---|---|
| 400 | INVALID_REQUEST | The request failed validation ( INVALID_REQUEST).Applies to 3 operations | Correct the fields named in the error details, then retry the request. |
| 400 | INVALID_REQUEST, IDEMPOTENCY_KEY_REQUIRED, ORDER_LINE_AMBIGUOUS, UNSUPPORTED_API_VERSION | Invalid command body, missing/invalid UUID Idempotency-Key, or a skuId on more than one line the command can still act on (ORDER_LINE_AMBIGUOUS, with the candidate lineRefs in details). Unknown or retired API-version override (UNSUPPORTED_API_VERSION). | Correct the request fields and supply a UUID Idempotency-Key. For ORDER_LINE_AMBIGUOUS, name that line by one of the lineRef values in details. Keep the same key when retrying the same command. For UNSUPPORTED_API_VERSION, choose a supported version from the API versioning guide. |
| 400 | INVALID_REQUEST, IDEMPOTENCY_KEY_REQUIRED, UNSUPPORTED_API_VERSION | Invalid command body or missing/invalid UUID Idempotency-Key. Unknown or retired API-version override ( UNSUPPORTED_API_VERSION).Applies to 13 operations
| Correct the request fields and supply a UUID Idempotency-Key. Keep the same key when retrying the same command. For UNSUPPORTED_API_VERSION, choose a supported version from the API versioning guide. |
| 400 | INVALID_REQUEST, ORDER_LINE_AMBIGUOUS, UNSUPPORTED_API_VERSION | Invalid query, a line the order does not have, or a skuId on more than one line (ORDER_LINE_AMBIGUOUS, with the candidate lineRefs in details). Unknown or retired API-version override (UNSUPPORTED_API_VERSION).Applies to 1 operations | Name exactly one line. For ORDER_LINE_AMBIGUOUS, name it by one of the lineRef values in details. For UNSUPPORTED_API_VERSION, choose a supported version from the API versioning guide. |
| 400 | INVALID_REQUEST, UNSUPPORTED_API_VERSION | The request failed validation ( INVALID_REQUEST). Unknown or retired API-version override (UNSUPPORTED_API_VERSION).Applies to 12 operations | Correct the fields named in the error details, then retry the request. For UNSUPPORTED_API_VERSION, choose a supported version from the API versioning guide. |
| 400 | UNSUPPORTED_API_VERSION | Unknown or retired API-version override ( UNSUPPORTED_API_VERSION).Applies to 3 operations | For UNSUPPORTED_API_VERSION, choose a supported version from the API versioning guide. |
| 401 | UNAUTHORIZED | Missing or invalid marketplace API key ( UNAUTHORIZED).Applies to 34 operations
| Send the marketplace API key for this seller as a Bearer token, then retry. |
| 403 | SUBSCRIPTION_EXCLUDES_ORDERS | The platform's subscription is inventory, which does not include orders (SUBSCRIPTION_EXCLUDES_ORDERS). Only orders and both subscriptions read and act on orders.Applies to 24 operations
| Do not retry. Ask Snapcaster to change the platform subscription to orders or both if the platform should handle orders. |
| 404 | ORDER_NOT_FOUND | No order matches this id for the authenticated seller ( ORDER_NOT_FOUND). Another seller's order also returns 404, so the response does not reveal whether it exists.Applies to 12 operations
| Check the order_id against GET /orders for the authenticated seller, then retry with that id. |
| 404 | ORDER_NOT_FOUND | No order matches this id for the authenticated seller ( ORDER_NOT_FOUND). Another seller's order also returns 404, so the response does not reveal whether it exists. An order of this seller that no test purchase of this seller created also returns 404 (ORDER_NOT_FOUND): the sandbox buyer acts only on orders from POST /sandbox/test-purchases. | Use an order_id from GET /sandbox/test-purchases/{ref} for this seller. |
| 404 | ORDER_NOT_FOUND, CANCELLATION_REQUEST_NOT_FOUND | No order matches this id for the authenticated seller ( ORDER_NOT_FOUND). Another seller's order also returns 404, so the response does not reveal whether it exists. No pending cancellation request with this id is on the order (CANCELLATION_REQUEST_NOT_FOUND). An unknown id, a request on another order, and a request already honored, declined or withdrawn all answer this.Applies to 1 operations | Read GET /orders/{orderId}/cancellation-requests; a request that is no longer pending needs no answer. |
| 404 | ORDER_NOT_FOUND, ORDER_ADDITION_OFFER_NOT_FOUND | Order additions are not yet available. No order matches this id for the authenticated seller ( ORDER_NOT_FOUND), or no add-on offer with this id is on the order (ORDER_ADDITION_OFFER_NOT_FOUND). Another seller's order also returns 404.Applies to 1 operations | Read GET /orders/{orderId}/addition-offers for the offer ids on the order. |
| 404 | ORDER_NOT_FOUND, ORDER_ADDITION_REQUEST_NOT_FOUND | Order additions are not yet available. No order matches this id for the authenticated seller ( ORDER_NOT_FOUND), or no add-on request with this id is on the order (ORDER_ADDITION_REQUEST_NOT_FOUND). Another seller's order also returns 404.Applies to 1 operations | Read GET /orders/{orderId}/addition-requests for the request ids on the order. |
| 404 | ORDER_NOT_FOUND, ORDER_ADDITION_REQUEST_NOT_FOUND | Order additions are not yet available. No order matches this id for the authenticated seller ( ORDER_NOT_FOUND), or the requestRef names no add-on request on the order (ORDER_ADDITION_REQUEST_NOT_FOUND). Another seller's order also returns 404.Applies to 1 operations | Check the order id against GET /orders and the request id against GET /orders/{orderId}/addition-requests. |
| 404 | ORDER_NOT_FOUND, ORDER_CHANGE_REQUEST_NOT_FOUND | No order matches this id for the authenticated seller ( ORDER_NOT_FOUND), or no change request with this id is on the order (ORDER_CHANGE_REQUEST_NOT_FOUND). | Read GET /orders/{orderId}/change-requests for the ids on the order. |
| 404 | ORDER_NOT_FOUND, ORDER_CHANGE_REQUEST_NOT_FOUND | No order matches this id for the authenticated seller ( ORDER_NOT_FOUND), or no change request with this id is on the order (ORDER_CHANGE_REQUEST_NOT_FOUND). An order of this seller that no test purchase of this seller created also returns 404 (ORDER_NOT_FOUND): the sandbox buyer acts only on orders from POST /sandbox/test-purchases.Applies to 1 operations | Read GET /orders/{orderId}/change-requests for the ids on the order. |
| 404 | TEST_PURCHASE_NOT_FOUND | No test purchase matches this ref for the authenticated seller ( TEST_PURCHASE_NOT_FOUND). Another seller's ref also returns 404.Applies to 1 operations | Use the test_purchase_ref the trigger returned to this seller. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS | IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, ADDRESS_VERIFICATION_NOT_RETRYABLE | IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. ADDRESS_VERIFICATION_NOT_RETRYABLE when the check already has a verdict. Applies to 1 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For ADDRESS_VERIFICATION_NOT_RETRYABLE, act on the verdict in address_verification; correct the address with POST /orders/{orderId}/corrections if it needs changing. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, CORRECTION_NOT_ALLOWED | IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. CORRECTION_NOT_ALLOWED when the order is past accepted.Applies to 1 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For CORRECTION_NOT_ALLOWED, the parcel has left; contact the buyer about the delivery instead. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, INSUFFICIENT_STOCK | IDEMPOTENCY_CONFLICT when the key was used with a different body, REQUEST_IN_PROGRESS while another request with this key runs, or INSUFFICIENT_STOCK when a line asks for more than the listing has available. Applies to 1 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or a new UUID. For INSUFFICIENT_STOCK, push more on-hand or ask for fewer cards. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, ORDER_ADDITION_OFFER_ALREADY_OUTSTANDING, ORDER_ADDITION_OFFER_NOT_OUTSTANDING, ORDER_ADDITION_OFFER_NOT_SENT, ORDER_ADDITION_OFFER_PRICE_CHANGED, ORDER_ADDITION_OFFER_INSUFFICIENT_STOCK, ORDER_ADDITION_OFFER_SHIPPING_CHANGED, ORDER_ADDITION_REQUEST_NOT_PENDING | Order additions are not yet available. IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. Or the offer cannot be sent as it stands: another offer is awaiting the buyer ( ORDER_ADDITION_OFFER_ALREADY_OUTSTANDING, details.offerRef); replacesOfferRef is not the outstanding offer (ORDER_ADDITION_OFFER_NOT_OUTSTANDING); the buyer is paying for the outstanding offer (ORDER_ADDITION_OFFER_NOT_SENT); a listing was repriced while the offer was priced (ORDER_ADDITION_OFFER_PRICE_CHANGED); the units cannot all be reserved (ORDER_ADDITION_OFFER_INSUFFICIENT_STOCK, details.shortfalls); the parcel's shipping changed while the offer was priced (ORDER_ADDITION_OFFER_SHIPPING_CHANGED); or requestRef is no longer pending (ORDER_ADDITION_REQUEST_NOT_PENDING). Nothing is written on any of these: a refused replacement leaves the original offer and its reservation as they were.Applies to 1 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For the ORDER_ADDITION codes, read GET /orders/{orderId}/addition-offers and your listings, then send a corrected offer under a new key. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, ORDER_ADDITION_OFFER_NOT_SENT | Order additions are not yet available. IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. ORDER_ADDITION_OFFER_NOT_SENT: the offer already ended, or the buyer is paying for it; details.status says which.Applies to 1 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For ORDER_ADDITION_OFFER_NOT_SENT, read GET /orders/{orderId}/addition-offers for the offer's current status. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, ORDER_ADDITION_PAYMENT_IN_FLIGHT | IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS, or ORDER_ADDITION_PAYMENT_IN_FLIGHT while the buyer is paying for cards added to the order, which cannot happen until order additions are available. Retry an in-progress command with the same key after Retry-After seconds. Applies to 2 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For ORDER_ADDITION_PAYMENT_IN_FLIGHT, retry after the buyer's payment for the added cards resolves; GET /orders/{orderId} shows the order once it has. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, ORDER_ADDITION_REQUEST_NOT_PENDING | Order additions are not yet available. IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. ORDER_ADDITION_REQUEST_NOT_PENDING: the request was already withdrawn, declined or answered with an offer; details.status says which.Applies to 1 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For ORDER_ADDITION_REQUEST_NOT_PENDING, read GET /orders/{orderId}/addition-requests; a request that is no longer pending needs no answer. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, ORDER_CHANGE_REQUEST_ALREADY_PENDING, SUPPORT_CASE_CLOSED | IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. ORDER_CHANGE_REQUEST_ALREADY_PENDING when the order already has a pending change request, from either party; details carries its id. SUPPORT_CASE_CLOSED when Snapcaster closed the order's support conversation while the report was being filed.Applies to 1 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For ORDER_CHANGE_REQUEST_ALREADY_PENDING, read GET /orders/{orderId}/change-requests and answer or withdraw the pending request first. For SUPPORT_CASE_CLOSED, file the report again with a new key; it opens a new conversation. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, ORDER_CHANGE_REQUEST_ALREADY_PENDING, SUPPORT_CASE_CLOSED | IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. ORDER_CHANGE_REQUEST_ALREADY_PENDING when the order already has a pending change request, from either party; details carries its id. SUPPORT_CASE_CLOSED when Snapcaster closed the order's support conversation while the request was being opened.Applies to 1 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For ORDER_CHANGE_REQUEST_ALREADY_PENDING, answer or withdraw the pending request first. For SUPPORT_CASE_CLOSED, retry with a new key. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, ORDER_CHANGE_REQUEST_NOT_PENDING | IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. ORDER_CHANGE_REQUEST_NOT_PENDING when the request was already answered, withdrawn or voided; details.status is its status now. | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For ORDER_CHANGE_REQUEST_NOT_PENDING, do not retry: the request needs no answer. |
| 409 | IDEMPOTENCY_CONFLICT, REQUEST_IN_PROGRESS, REQUEST_ALREADY_OPEN, CANCELLATION_REQUEST_LIMIT_REACHED | IDEMPOTENCY_CONFLICT or REQUEST_IN_PROGRESS. Retry an in-progress command with the same key after Retry-After seconds. REQUEST_ALREADY_OPEN when a cancellation request is already pending on the order. CANCELLATION_REQUEST_LIMIT_REACHED when the order already had three. Applies to 1 operations | For REQUEST_IN_PROGRESS, wait Retry-After seconds and retry the same key and body. For IDEMPOTENCY_CONFLICT, reuse the original body or create a new UUID for a different operation. For REQUEST_ALREADY_OPEN, decline the pending request first. For CANCELLATION_REQUEST_LIMIT_REACHED, use another test purchase. |
| 409 | SELLER_SOURCE_EXCLUSIVE | The seller's inventory source is not platform (SELLER_SOURCE_EXCLUSIVE). Only platform-source sellers can write listings through the integration API. A seller uses one inventory source at a time.Applies to 3 operations | Use the seller’s declared inventory source, or ask Snapcaster to move the seller to the platform source. |
| 409 | SELLER_SOURCE_EXCLUSIVE, STALE_SNAPSHOT | The seller uses another inventory source, or asOf precedes an existing purge. Applies to 1 operations | Use the declared inventory source. For STALE_SNAPSHOT, discard the delayed purge; use a newly measured snapshot for a new purge. |
| 409 | WEBHOOK_ENDPOINT_NOT_REGISTERED | Your platform has no webhook endpoint registered, so there is nowhere to send the test. Applies to 1 operations | Ask Snapcaster to register your receiver URL and signing secret for this environment, then retry. |
| 413 | BATCH_TOO_LARGE, PAYLOAD_TOO_LARGE | The request exceeds the 1,000-item limit ( BATCH_TOO_LARGE). The body is larger than this route accepts (PAYLOAD_TOO_LARGE).Applies to 3 operations | Split the write into batches of at most 1,000 items and retry each batch. Send a smaller body and retry. |
| 413 | PAYLOAD_TOO_LARGE | The body is larger than this route accepts ( PAYLOAD_TOO_LARGE).Applies to 20 operations
| Send a smaller body and retry. |
| 422 | CANCELLATION_NOT_ALLOWED | The buyer could not ask for this cancellation ( CANCELLATION_NOT_ALLOWED): the order has shipped, or a line has fewer units left to cancel than asked.Applies to 1 operations | Ask before you mark the order shipped, or name fewer units. |
| 422 | CORRECTION_CHANGES_DELIVERY_REGION, CORRECTION_UNCHANGED | The correction changes the province or country ( CORRECTION_CHANGES_DELIVERY_REGION), or names the current ship_to again (CORRECTION_UNCHANGED).Applies to 1 operations | For CORRECTION_CHANGES_DELIVERY_REGION, cancel the order so the buyer can check out again to the new region. For CORRECTION_UNCHANGED, read ship_to; the order already ships there. |
| 422 | INVALID_TRANSITION | The requested status change is not allowed ( INVALID_TRANSITION). Examples include moving to an earlier status, refunding before shipping, or cancelling after shipping.Applies to 2 operations | Read the current order status and choose an allowed change. Use the cancellation or refund endpoint for those actions. |
| 422 | INVALID_TRANSITION, INVALID_REQUEST | The requested status change is not allowed ( INVALID_TRANSITION), or the supplied dispatch details do not match the order's saved shipping option (INVALID_REQUEST).Applies to 1 operations | Read the current order status and choose an allowed change. Supply tracking only if the order's saved shipping option requires it. |
| 422 | ORDER_ADDITION_NOT_ELIGIBLE, ORDER_ADDITION_SKU_UNKNOWN, ORDER_ADDITION_OFFER_LISTING_MISSING, ORDER_ADDITION_OFFER_PRICE_ABOVE_LISTING, ORDER_ADDITION_OFFER_SHIPPING_CAPACITY, ORDER_ADDITION_OFFER_SHIPPING_OPTION_INVALID, ORDER_ADDITION_OFFER_SHIPPING_NOT_REQUIRED, ORDER_ADDITION_OFFER_SHIPPING_DOWNGRADE, ORDER_ADDITION_OFFER_SHIPPING_UNSTATED, ORDER_ADDITION_OFFER_BELOW_MINIMUM, ORDER_ADDITION_OFFER_TAX_UNRESOLVED | Order additions are not yet available. The order cannot carry an add-on ( ORDER_ADDITION_NOT_ELIGIBLE, details.reasons as in the list's eligibility); a skuId is not in the catalog (ORDER_ADDITION_SKU_UNKNOWN); the seller has no live listing for one (ORDER_ADDITION_OFFER_LISTING_MISSING); a unitPriceCents is above the listing price (ORDER_ADDITION_OFFER_PRICE_ABOVE_LISTING); the combined parcel does not fit the shipping already paid for or the option named (ORDER_ADDITION_OFFER_SHIPPING_CAPACITY, details maxCards, remainingUnits, offeredUnits, upgradeOffered); shippingOptionId is not one of the seller's typed options (ORDER_ADDITION_OFFER_SHIPPING_OPTION_INVALID); the parcel already fits, so no upgrade may be charged (ORDER_ADDITION_OFFER_SHIPPING_NOT_REQUIRED); the option costs less than the shipping already paid (ORDER_ADDITION_OFFER_SHIPPING_DOWNGRADE); the order records no shipping evidence to upgrade from (ORDER_ADDITION_OFFER_SHIPPING_UNSTATED); the total is below the payment minimum (ORDER_ADDITION_OFFER_BELOW_MINIMUM, details.minimumCents); or the delivery province cannot be taxed (ORDER_ADDITION_OFFER_TAX_UNRESOLVED). These are the codes the seller dashboard answers for the same offer.Applies to 1 operations | Correct the offer: read GET /shipping-options for an option that carries the parcel, and price each line at or below its listing price. An ineligible order needs no offer. |
| 422 | ORDER_CHANGE_REQUEST_NOT_ALLOWED | The request is not the seller's to answer this way ( ORDER_CHANGE_REQUEST_NOT_ALLOWED): the seller raised it, so the buyer answers it, or an address change came after the order shipped.Applies to 1 operations | Do not retry. Read GET /orders/{orderId}/change-requests; a request the seller raised is answered by the buyer. |
| 422 | ORDER_CHANGE_REQUEST_NOT_ALLOWED | The request is not the seller's to answer this way ( ORDER_CHANGE_REQUEST_NOT_ALLOWED): the seller raised it, so the buyer answers it. A fulfillment report has no decline.Applies to 1 operations | Do not retry. Read GET /orders/{orderId}/change-requests; a request the seller raised is answered by the buyer. |
| 422 | ORDER_CHANGE_REQUEST_NOT_ALLOWED | The buyer raised this request, so only the buyer can withdraw it ( ORDER_CHANGE_REQUEST_NOT_ALLOWED).Applies to 1 operations | Do not retry. Answer a buyer request with POST /orders/{orderId}/change-requests/{requestId}/accept or .../decline. |
| 422 | ORDER_CHANGE_REQUEST_NOT_ALLOWED, INVALID_TRANSITION | The buyer cannot answer this request this way ( ORDER_CHANGE_REQUEST_NOT_ALLOWED): the buyer raised it, so the seller answers it, or a substitute no longer passes its rule (details names the SKU and the rule). INVALID_TRANSITION: the order moved so the answer cannot run.Applies to 1 operations | Answer only a fulfillment report this seller filed. For a substitute that fails, take another answer or file a new report. |
| 422 | ORDER_CHANGE_REQUEST_NOT_ALLOWED, INVALID_TRANSITION, SUPPORT_CASE_WINDOW_CLOSED | The report cannot be filed, with the codes the seller dashboard returns. ORDER_CHANGE_REQUEST_NOT_ALLOWED: the order has shipped or ended, or has no buyer to answer; the removals cover every remaining unit; or a substitute fails its rule (not a SKU the seller lists live, another catalog product, the line's own SKU or another SKU on the order, too little stock, a credit above what the line is worth, or a quantity smaller than the line's remaining units). INVALID_TRANSITION: a line has nothing left, or a quantity exceeds what it has left. SUPPORT_CASE_WINDOW_CLOSED: the order is too old for a support conversation, which every report opens or joins.Applies to 1 operations | Do not retry the same body. Read the message, then fix the line it names, pick a substitute from GET /orders/{orderId}/substitute-candidates, or cancel or remove the units instead. |
| 422 | ORDER_CHANGE_REQUEST_NOT_ALLOWED, INVALID_TRANSITION, SUPPORT_CASE_WINDOW_CLOSED | The buyer could not ask for this change, with the codes the buyer gets. ORDER_CHANGE_REQUEST_NOT_ALLOWED: the order is cancelled or refunded, or an address_change came after it shipped. INVALID_TRANSITION: a line has nothing left to remove. SUPPORT_CASE_WINDOW_CLOSED: the order is too old for a support conversation.Applies to 1 operations | Do not retry the same body. Read the message, then change the request. |
| 422 | TEST_LISTING_NOT_BROWSABLE, SHIPPING_OPTION_INVALID, TEST_PURCHASE_LIMIT_EXCEEDED | TEST_LISTING_NOT_BROWSABLE when a SKU has no browsable listing for this seller, SHIPPING_OPTION_INVALID when the shipping option is not the seller's or cannot carry the cards, or TEST_PURCHASE_LIMIT_EXCEEDED when merchandise and shipping total more than 25000 cents. Applies to 1 operations | Check the listing with GET /listings until it reads browsable, omit shippingOptionId to use the cheapest option that fits, or buy fewer or cheaper cards. |
| 429 | ADDRESS_VERIFICATION_RETRY_TOO_SOON | The failed check ran less than a minute ago ( ADDRESS_VERIFICATION_RETRY_TOO_SOON). The message says how many seconds remain.Applies to 1 operations | Wait a minute after the last check, then retry with a new Idempotency-Key. |
| 429 | RATE_LIMITED | The per-seller item rate ceiling was exceeded ( RATE_LIMITED).Applies to 3 operations | Wait the Retry-After duration in seconds, then retry with bounded retries and jitter. |
| 429 | RATE_LIMITED | More than 5 test events in the last 60 seconds for this platform ( RATE_LIMITED).Applies to 1 operations | Wait the Retry-After duration in seconds, then retry. |
| 429 | RATE_LIMITED | More than 20 test purchases in the last hour for this platform ( RATE_LIMITED).Applies to 1 operations | Wait the Retry-After duration in seconds, then retry. |
| 500 | INTERNAL_ERROR | An unexpected failure ( INTERNAL_ERROR).Applies to 37 operations
| Retry with bounded retries and jitter. If the failure persists, contact Snapcaster with the X-Correlation-ID response header. |
| 503 | TEST_PURCHASE_NOT_AVAILABLE | This deployment cannot run a test purchase right now ( TEST_PURCHASE_NOT_AVAILABLE): it is not the sandbox, its payments are not in test mode, or its sandbox buyer is missing.Applies to 1 operations | Call the sandbox API. If this persists there, contact Snapcaster with the X-Correlation-ID response header. |
| 503 | TEST_PURCHASE_NOT_AVAILABLE | This deployment cannot act as the sandbox buyer right now ( TEST_PURCHASE_NOT_AVAILABLE): it is not the sandbox, its payments are not in test mode, or its sandbox buyer is missing. | Call the sandbox API. If this persists there, contact Snapcaster with the X-Correlation-ID response header. |
Per-item failures
A successful HTTP response can contain rejected items. Inspect every result and handle its code separately.
| HTTP | Code | Meaning | Do this |
|---|---|---|---|
| 200 | INVALID_REQUEST | The item failed validation. Applies to 3 operations | Correct the fields named in reason before submitting this item again. |
| 200 | PRODUCT_MISMATCH | The productId names a different product than the canonical catalog holds for the skuId. Snapcaster stored nothing for the item and left any existing listing for the SKU unchanged.Applies to 3 operations | Send the productId that reason names, or omit productId so Snapcaster takes it from the catalog. |
| 200 | SNAPSHOT_CONFLICT | The same snapshot instant was used with different contents. Applies to 3 operations | Retry the original contents, or measure current stock and send it with its actual capture time. |
| 200 | STALE_SNAPSHOT | The snapshot is older than the retained listing or purge watermark. Applies to 3 operations | Discard the delayed snapshot. Measure current stock before sending a new snapshot; do not relabel stale stock with a newer timestamp. |
Each operation reference lists its errors and how to resolve them.
Need help?
The email includes this page and selects sandbox as the environment. Update it if you need help with production.
Never include an API key or signing secret in the message.