Error reference

HTTP statuses, canonical error codes, and recovery actions.

TopicsOperate

Every Seller API error code, what causes it, whether retrying is safe, and how to fix it.

Error recovery overview#

Diagram

API error responses include a doc_url that links directly to the relevant section on this page. If you arrived here from an error response, you are already at the right place.

When several checks refuse a sale, you get the first in this order. POST /orders/preview, /orders/hold, /orders/reserve, POST /orders and the blockedReason on GET /availability?country= all use it:

  1. Your selling footprint: the country (FOOTPRINT_COUNTRY_NOT_DECLARED), then the currency (FOOTPRINT_CURRENCY_NOT_DECLARED).
  2. What your agreement or partner access grants: the territory (TERRITORY_NOT_GRANTED), then the currency (CURRENCY_NOT_PERMITTED_BY_TERM).
  3. Access to the product: the share, exclusions and your allocation.
  4. Territory: release exclusions, SKU and contract region locks, restricted countries.
  5. The catalog price (CATALOG_PRICE_NOT_SET, or a price echo that does not match).
  6. The priced currency (CURRENCY_NOT_PRICED_FOR_COUNTRY).
  7. The sales channel (SALES_CHANNEL_NOT_PERMITTED).
  8. The buyer checks (geo and verification).

Fix the code you got and retry; a later check can still refuse.

The error envelope#

Every error returns the same flat JSON body (fields at the top level — not nested under error):

JSON
{
  "code": "NO_AVAILABLE_KEYS",
  "message": "Insufficient inventory: requested 2, available 0",
  "recoverable": false,
  "hint": "Check GET /availability first to see allocation and inventory",
  "doc_url": "https://docs.avrix.io/seller-api/errors#no-available-keys",
  "requestId": "req_01J8XYZ...",
  "timestamp": "2026-08-05T09:14:22.108Z",
  "details": {
    "requested": 2,
    "available": 0,
    "recommendedAction": "refund_buyer"
  },
  "error": "Insufficient inventory: requested 2, available 0"
}
FieldUse
codeBranch on this. Stable across releases. Never parse message.
messageHuman-readable. Wording may change; do not match on it.
recoverableWhether the condition may resolve on retry. Not the same as "safe to retry blindly".
hintShort remediation guidance.
doc_urlDeep link to the section on this page.
requestIdLog this. Quote it in every support request.
timestampISO-8601 time the error was formed.
detailsStructured context, varying by code. May include recommendedAction, and — when the fix lives in the Console — consoleUrl + consoleAction (see below). Footprint refusals also carry fixItUrl with the countryCode or currencyCode seen; consumer geo refusals carry declaredCountry and, when the buyer IP resolved, detectedCountry.
errorDeprecated. String alias of message for older clients. Do not read error.code — error is a string, not an object.

Fix it in the Console. When the cause can be resolved by the company that owns the API key, details.consoleUrl is an absolute link to the right Console page (scoped to that company, never to the shared sandbox catalog) and details.consoleAction is a stable label you can branch on:

consoleActionConsole pageTypical codes / decisionCode
review_partner_contractsPartners → ContractsCONTRACT_NOT_ACTIVE, NO_ACTIVE_BMA, API_MODEL_AGREEMENT_REQUIRED, BUSINESS_MODEL_NOT_ALLOWED, MINIMUM_ORDER_VIOLATION; CONNECTION_NOT_ACTIVE, MCA_NOT_ACTIVE, BMA_NOT_SIGNED, SKU_SHARE_TERM_MISMATCH
review_allocationsCommerce → AllocationsALLOCATION_EXCEEDED, NO_AVAILABLE_KEYS; ALLOCATION_PAUSED, ALLOCATION_REVOKED
manage_api_keysSettings → API keysINSUFFICIENT_SCOPE, IP_NOT_ALLOWED, ALLOWLIST_REQUIRED, KEY_ENVIRONMENT_MISMATCH, PRODUCTION_ACCESS_NOT_APPROVED
complete_kybSettings → KYBKYB_NOT_VERIFIED, TREASURY_CAPABILITY_MISSING
top_up_walletFinance → WalletINSUFFICIENT_WALLET_BALANCE, PAYMENT_NOT_CLEARED
review_partner_catalogCatalog → ProductsPRODUCT_NOT_SELLABLE, TERRITORY_*, SKU_REGION_UNRESOLVED, ACTIVATION_REGION_*, CATALOG_PRICE_NOT_SET, INVALID_CATALOG_PRICE; SKU_SHARE_MISSING, SKU_SHARE_SUSPENDED
review_commercial_settingsSettings → CommercialFOOTPRINT_COUNTRY_NOT_DECLARED, FOOTPRINT_CURRENCY_NOT_DECLARED (their fixItUrl is the same absolute link)

Codes whose fix is in your own request (validation, idempotency, price echo) or in Avrix operations (rate limits, timeouts) carry no consoleUrl. Territory, activation and price guard failures on POST /orders and POST /keys/pull now return the same structured details (skuId, countryCode, allowedCountryCodes, catalogUnitPriceCents, …) that POST /orders/preview already returned, instead of only pullError.

Always log requestId. It is how Avrix correlates your report with server-side traces, and a support request without one takes substantially longer to resolve.

Retry policy#

ClassRetry?How
5xxYesExponential backoff, same Idempotency-Key
429YesWait for Retry-After
409 IDEMPOTENCY_REQUEST_IN_FLIGHTYesWait for Retry-After
Timeout, no responseYesSame key, same body. See unknown outcome
409 NO_AVAILABLE_KEYSNoDeterministic
409 ALLOCATION_EXCEEDEDNoRequest a larger allocation (POST /allocations/requests) or lower the quantity
422NoFix the request first
401, 403NoCredential or permission problem

A 5xx after you charged the buyer: retry before you refund#

Some 5xx answers arrive after the order was fulfilled and billed: 503 IDEMPOTENCY_STORE_UNAVAILABLE when the order completed but its replay record could not be saved, 504 HOT_PATH_TIMEOUT when the database committed but the answer was lost, and any network timeout or dropped connection. Refunding on those leaves a fulfilled, billed order behind, and a refund returns its keys to quarantine. One rule covers all of them:

  1. Retry with the same Idempotency-Key, the same body and the same orderReference, with backoff. If the order went through, the retry replays it (replayed: true) and bills nothing again. If it did not, the retry places it.
  2. Still no answer? Look it up. GET /orders?orderReference= shows whether keys were delivered.
  3. Keys delivered but you never received them? POST /orders/recover-keys returns them.
  4. Refund at your PSP only when the lookup shows no live keys for the reference.

Failed responses are never cached. Only successful (2xx) responses are stored for Idempotency-Key replay. After any 4xx/5xx, fix the underlying cause (KYB, wallet balance, stock, prices) and retry with the same key — the request is re-evaluated against live state. You never need to rotate the key to escape a stale error.


Edge challenges (HTML 403)#

The API is served through an edge network that protects the platform against abusive traffic. A client that sends aggressive bursts (see rate limits) can be challenged at the edge before the request reaches the API: the response is a 403 with an HTML body instead of the JSON error envelope, and it carries no X-Request-Id or rate-limit headers.

How to tell the three rejection shapes apart:

SignalMeaning
403 + JSON envelope with codeAuthorization problem — see the codes below
403 + HTML body, no X-Request-IdEdge challenge — your traffic profile tripped platform protection
429 + JSON + Retry-AfterAPI rate limiting — back off and retry

Fix. Treat an HTML 403 as a signal to slow down, not something to retry. Reduce your request rate, prefer cached reads (send If-None-Match, honour Cache-Control), and spread bursts over time. The challenge decays automatically after a cool-down. If a well-behaved integration keeps being challenged, contact support with your egress IP addresses — sustained high-volume integrations should make sure every egress IP is on the key allowlist so the edge bypass applies.

Authentication and authorisation#

unauthorized#

UNAUTHORIZED · 401 · Recoverable

The API key was not accepted: malformed header, revoked key, or wrong environment.

Fix. Verify the header is Authorization: Bearer avrix_sk_… with no doubled prefix, quotes, or non-ASCII characters. Confirm the key is active in the Console. Call GET /whoami to check the environment. See Authentication.

forbidden#

FORBIDDEN · 403 · Not recoverable

The credential is valid but not permitted to perform this operation on this resource.

A missing scope. On contract dates before 2026-12-01, and for requests that do not pin a date, a key without the scope an operation needs gets this code: details.missingScope names a scope the operation needs and details.requiredScopes lists the scopes the refusal has always reported. Where an operation has since started accepting more scopes, that list can be shorter than the scope matrix; any scope the matrix lists for the operation works. A key with no scopes at all gets details.reason: "scopes_required"; there is no implicit default. On 2026-12-01 and later the same refusal is INSUFFICIENT_SCOPE.

Fix. With details.missingScope: scopes cannot be added to an existing key, so create a new key that holds one of the operation's scopes (see the scope matrix), move your service to it, then revoke the old key. Without it: confirm the key belongs to the company that owns the resource.

insufficient-scope#

INSUFFICIENT_SCOPE · 403 · Not recoverable

The API key holds none of the scopes this operation accepts. Nothing was changed.

  • On contract date 2026-12-01 and later (pinned with X-Avrix-Api-Version, or next), every operation answers a missing scope with this code. details.requiredScopes lists every scope the operation accepts, preferred first; holding any one of them is enough. details.missingScope names the preferred scope. details.scopeMode is anyOf, or any for the few operations that accept any Seller API scope (requiredScopes then lists them all). A key with no scopes at all also carries details.reason: "scopes_required". On earlier dates the same refusal is FORBIDDEN.
  • On every contract date, POST /keys returns this code when the calling key cannot give the new key the scopes it would receive (includeFinanceScope without seller:finance:read on the calling key, or a calling key that holds none of the scopes a new key gets).

Fix. Issue a key that holds one of details.requiredScopes, preferably the first (see the scope matrix), move your service to it, then revoke the old key. For POST /keys, create the key with a calling key that holds those scopes, or in the Console.

ip-not-allowed#

IP_NOT_ALLOWED · 403 · Not recoverable

Your source address is not on the key's allowlist.

Fix. Call GET /whoami-ip from the failing environment to see the address Avrix observed, then add it. A populated list is enforced on every key; IP allowlist has the full rule.

allowlist-required#

ALLOWLIST_REQUIRED · 403 · Not recoverable

A production key has an empty allowed_ips list and no trusted workload binding while GET /whoami → capabilities.requireProductionAllowlistEnabled is true. Sandbox keys are not affected.

Fix. Set a non-empty IP allowlist via Settings → Integrations → API Keys or PATCH /api-keys/{id}/allowed-ips (older path PATCH /keys/{id}/allowed-ips), or bind the key to a trusted workload. Discover your egress with GET /whoami-ip, then retry from an allowlisted address. See IP allowlist.

ip-not-resolvable#

IP_NOT_RESOLVABLE · 403 · Not recoverable

The key has a populated allowlist, but Avrix could not determine a client IP from the request headers — so the allowlist check cannot run safely.

Fix. Ensure your edge or proxy forwards a usable client address (for example X-Forwarded-For is not stripped). Call GET /whoami-ip from the same path to confirm what Avrix observes.

workload-identity-invalid#

WORKLOAD_IDENTITY_INVALID · 403 · Not recoverable

The key is bound to a trusted workload (OIDC workload identity) instead of an IP allowlist, and the request's X-Avrix-Workload-Token is missing, expired, not signed by the bound issuer, or names a different audience or subject. details.reason says which.

Fix. Send the current OIDC token your hosting platform issues to the bound workload in X-Avrix-Workload-Token on every request, or update the key's trusted workload under Settings → Integrations → API Keys. See IP allowlist.

key-environment-mismatch#

KEY_ENVIRONMENT_MISMATCH · 401 · Not recoverable

The API key's environment (production or sandbox) does not match the request environment. Both environments share one host, so there are two causes: a production key sent with X-Avrix-Sandbox: true, or a sandbox key used on a deployment where the sandbox is disabled. details carries keyEnvironment and requestEnvironment.

Fix. Remove X-Avrix-Sandbox from production calls. On a deployment without the sandbox, use a production key. GET /whoami with the same key and headers shows data.key.environment and requestEnvironment. See Sandbox to production.

production-access-not-approved#

PRODUCTION_ACCESS_NOT_APPROVED · 403 · Not recoverable

Your seller company is not approved for production Seller API access. Sandbox keys continue to work. The first refused call records your request; details.productionAccess carries status (requested) and requestedAt.

Fix. Complete certification and ask Avrix operations to enable production API access. Follow the state with GET /whoami and a sandbox key: data.productionAccess.status turns approved when production keys work. See Go live and Certification.

api-model-agreement-required#

API_MODEL_AGREEMENT_REQUIRED · 403 · Not recoverable

Your company has not signed the API Revenue Share Channel Terms. Sandbox keys can still be created; production keys cannot.

Fix. In the Avrix Console open Settings → Commercial Agreements, sign the API Revenue Share Channel Terms, then create the production key. Live traffic on production still requires Avrix to enable production API access (PRODUCTION_ACCESS_NOT_APPROVED). See Go live.


Request validation#

unsupported-api-version#

UNSUPPORTED_API_VERSION · 400 · Recoverable

The request sent an X-Avrix-Api-Version value that this host does not support.

Fix. Omit the header (the request is then served the stamped default, 2026-09-01), or send a supported contract date; details.supportedVersions lists them. See Versioning and compatibility.

invalid-request-id#

INVALID_REQUEST_ID · 400 · Recoverable

Contract date 2026-12-01 and later. The X-Request-Id request header is not 8 to 128 characters from A-Z, a-z, 0-9, _, ., : and -. Nothing was read or changed; details gives the format (minLength, maxLength, pattern). Earlier contract dates echo any value as sent.

Fix. Send a UUID, a ULID or another id in that format, or omit the header and log the X-Request-Id the response returns. Every id in the format can be looked up later with GET /requests/{requestId}. See Monitoring and support.

validation-failed#

VALIDATION_FAILED · 422 · Recoverable

The request failed schema validation.

Fix. Use details.issues — an array of field and message pairs pinpointing each problem. For query parameters, match the OpenAPI definition. For path parameters, UUID segments must be valid UUIDs.

On the order surfaces (POST /orders, /orders/preview, /orders/hold, /orders/reserve), details.issues lists every invalid or missing field of the request in one response, so you can fix them all before you resend. This also holds when the refusal is one of the per-field codes (SALES_COUNTRY_REQUIRED, TAX_DECLARATION_REQUIRED, SALES_CHANNEL_REQUIRED, EXPECTED_UNIT_PRICE_REQUIRED): the top-level code and message are unchanged and that field comes first in the list. Each issue may also carry code (the refusal that field alone would get) and, for an enum such as salesChannel, allowedValues.

On contract date 2026-12-01 and later, GET /orders?status= answers this for a status the environment's order listing cannot serve yet; details.issues[0].allowedValues lists the values it can.

bad-request#

BAD_REQUEST · 400 · Not recoverable

Malformed request that failed before schema validation — unparseable JSON, wrong content type.

not-found#

NOT_FOUND · 404 · Not recoverable

The resource does not exist, or is not visible to your company. Avrix does not distinguish the two, by design.

Fix. For SKUs, confirm it appears in GET /allocations. A SKU that exists on the platform but is not shared or allocated to you returns 404.

conflict#

CONFLICT · 409 · Recoverable

The resource state conflicts with the request. details.reason names the conflict when there is one.

On contract date 2026-12-01 and later, answering a promotion share or deal that already has a different answer (POST /promotions/shares/{shareId}/accept, .../decline, POST /promotions/deals/{responseId}/respond) answers 409 CONFLICT with details.reason SHARE_ALREADY_RESPONDED or RESPONSE_ALREADY_ANSWERED and details.currentStatus. The promotion keeps its first answer. Earlier contract dates answer 400 BAD_REQUEST.

Also on 2026-12-01 and later, a promotion whose state no longer allows the call answers 409 CONFLICT instead of 400 BAD_REQUEST. details.reason is SHARE_EXPIRED, PROMOTION_STARTED or RESPONSE_DEADLINE_PASSED (too late to answer: the offer is now expired), PROMOTION_WITHDRAWN (the vendor withdrew the deal), or NOT_ACCEPTED (GET /promotions/shares/{shareId}/discounts for a share you have not accepted; details.currentStatus names its state). Answer offers before their respond_by.

On contract date 2026-12-01 and later, GET /finance/invoices/{invoiceId}/reconciliation for an invoice you owe that has no settlement (reconciliationAvailable: false, typically an invoice of the earlier per-report billing model) answers 409 CONFLICT with details.reason RECONCILIATION_NOT_AVAILABLE and details.invoicePath. Earlier contract dates answer 404, the same as for an invoice that is not yours. Read the invoice at details.invoicePath instead, and do not retry.

Allocation requests use these reasons. On POST /allocations/requests: ALLOCATION_REQUEST_PENDING (a request on the allocation is already waiting; details.pendingRequestId names it, so read it or cancel it), grant_not_requestable (the allocation is revoked), ALLOCATION_CEILING_EXCEEDS_STOCK, ALLOCATION_GRANT_GROWTH_NOT_AUTHORISED, and the Content Owner or agreement gates model_not_activated, sku_not_found, sku_not_enabled_for_model, no_connection, deal_agreement, deal_agreement_pending_publisher and deal_agreement_pending_seller. On POST /allocations/requests/{id}/cancel: ALLOCATION_REQUEST_ALREADY_RESOLVED (the Content Owner decided it first; details.state says how). On PATCH /allocations/{id}, contract date 2026-12-01 and later: allocation_revoked.

Answering an access proposal (POST /access/proposals/{id}/accept or /decline) keeps the generic top-level code and names the reason in details.accessCode, with details.proposalId:

details.accessCodeStatus and codeMeaningWhat to do
AMENDMENT_NOT_FOUND, AMENDMENT_NOT_ACCESS, AMENDMENT_SELF_ACCEPT_FORBIDDEN, AMENDMENT_SELF_DECLINE_FORBIDDEN404 NOT_FOUNDNo open access proposal with this id is addressed to youRe-read GET /access/proposals; use only ids it lists
AMENDMENT_NOT_PROPOSED409 CONFLICTThe proposal was already answered, or the vendor withdrew itRe-read GET /access/proposals and GET /whoami (accessByPublisher); do not retry
AMENDMENT_TERM_NOT_ACTIVE409 CONFLICTThe agreement it amends is not active (paused, ending or ended)Check GET /partners/{connectionId}/agreements; the vendor must propose again on an active agreement
AMENDMENT_TERM_NOT_FOUND409 CONFLICTThe agreement it amends no longer existsAsk the vendor for a new proposal
ACCESS_TERMS_NOT_ACCEPTED409 CONFLICTYour company has not accepted the updated platform terms that partner access needsAccept them in the console, then answer again
ACCESS_FX_NOT_COVERED422 VALIDATION_FAILEDAccepting a currency: no reference rate from the last 14 days converts it to the agreement's payment currency (details.currencyPair)Ask the vendor; retrying does not help until a rate exists
ACCESS_CURRENCY_NOT_ALLOWED422 VALIDATION_FAILEDAccepting a currency the vendor no longer allows thereAsk the vendor for a new proposal

A decline can only be refused with the 404 and 409 reasons; the currency reasons apply to accepting. A retry with the same Idempotency-Key replays the first answer instead of refusing.

Fix. Read the current state (details.currentStatus, or a GET of the resource) before deciding again. Do not retry the same request: it conflicts again.

payload-too-large#

PAYLOAD_TOO_LARGE · 413 · Recoverable

The JSON body exceeds the size limit. Reduce it — for bulk orders, split into smaller batches.


Idempotency#

idempotency-key-mismatch#

IDEMPOTENCY_KEY_MISMATCH · 409 · Not recoverable

The Idempotency-Key was already used with a different request body.

Fix. Reuse a key only when retrying a byte-identical request. Compare details.requestBodyHash with the first request to find the difference. If this is genuinely a new order, use a new key. Do not treat this as a form-validation (422) failure — the HTTP status is 409.

Bodies are compared by canonical-JSON hash, so key ordering and whitespace do not matter — a mismatch means real content differs.

On contract date 2026-12-01 and later, the path parameters are compared too: the same key and body sent to another allocation (PATCH /allocations/{id}) or another key (POST /orders/{orderId}/keys/{keyId}/replace) is a mismatch, where earlier dates replayed the first answer without changing the second target. Use one key per target.

idempotency-key-required#

IDEMPOTENCY_KEY_REQUIRED · 400 · Not recoverable

The write needs an Idempotency-Key header and the request had none, or the value was not in the accepted format. details.idempotency is key_missing or key_invalid; details.maxLength and details.pattern state the format. Nothing was changed. This code is returned on contract date 2026-12-01 and later; on earlier dates the same refusal is 400 BAD_REQUEST with the message "Idempotency-Key header is required for this operation." for both cases.

Fix. Send Idempotency-Key with 1 to 64 characters from A-Z, a-z, 0-9, - and _ (a UUID fits). Generate it once per logical write, store it with your order, and send the same key and body on every retry. The API reference marks every operation that requires the header.

idempotency-request-in-flight#

IDEMPOTENCY_REQUEST_IN_FLIGHT · 409 · Recoverable

Another request with this key is currently executing.

Fix. Wait for Retry-After seconds and retry with the same key. Do not issue a new key.

idempotency-store-unavailable#

IDEMPOTENCY_STORE_UNAVAILABLE · 503 · Recoverable

The idempotency store is temporarily unavailable. Two cases share this code:

  • Before the order ran (the message says the store is unavailable): the request was rejected rather than executed, to avoid a duplicate that could not be detected.
  • After the order ran (the message says the order was processed): the keys were delivered and billed, but the record that lets a retry replay the result could not be saved.

Fix. In both cases retry with the same Idempotency-Key, body and orderReference after a short delay; never refund on this code alone. See A 5xx after you charged the buyer.


Contracts and permissions#

contract-not-active#

CONTRACT_NOT_ACTIVE · 403 · Not recoverable

The connection or a required contract — MCA or API BMA — is not active, or the agreement that granted this SKU is paused. POST /orders/preview, /orders/hold, /orders/reserve, /orders and /keys/export all answer this code (with previewError / holdError / reserveError / skuResolve: "CONTRACT_NOT_ACTIVE") — never SKU_NOT_FOUND — so a paused agreement is not mistaken for a catalog problem. Your allocation is intact and becomes sellable again when the agreement is resumed; nothing needs to be re-requested.

Fix. Commercial, not technical. Contact the vendor. Check hasActiveBma on GET /whoami. Show the product as unavailable rather than removing it from your catalog.

minimum-order-violation#

MINIMUM_ORDER_VIOLATION · 422 · Not recoverable

Quantity is below the minimum for this connection. details gives the minimum.

payment-not-cleared#

PAYMENT_NOT_CLEARED · 402 · Not recoverable

Allocation payment must be confirmed before keys are released. This concerns your settlement with Avrix, not your buyer's payment. POST /orders/preview answers it too, before you charge the buyer, and GET /allocations reports the grant as sellable: false with the PAYMENT_NOT_CLEARED readiness blocker in advance.

Fix. If you have already charged the buyer, refund at your PSP. Contact support if settlement is complete but pulls still fail.

business-model-not-allowed#

BUSINESS_MODEL_NOT_ALLOWED · 403 · Not recoverable

The SKU's allowed_business_models allow-list does not include the allocation's distribution model. Seller API partnerships use the API business model — the SKU must allow api.

Fix. Ask the vendor to enable the SKU for the API distribution model, or use an allocation on an enabled model. details.remediation repeats the guidance.

insufficient-wallet-balance#

INSUFFICIENT_WALLET_BALANCE · 402 · Not recoverable

Not currently returned on Seller API pulls or orders. The code remains reserved for future prepaid / wholesale wallet settlement. Console wallet mutations may still surface it when a withdraw or convert exceeds available balance.

Fix. When this code returns on a pull or order again, top up the wallet or reduce quantity. If you already charged the buyer, refund at your PSP — Avrix does not auto-refund.

kyb-not-verified#

KYB_NOT_VERIFIED · 403 · Recoverable

The seller company has not completed Airwallex account verification (KYB), so settlement is not possible yet. Nothing is wrong with the request body — do not audit your payload.

Fix. An account admin must finish verification in Settings → Verification. Once the account reaches the ACTIVE state, retry with the same Idempotency-Key; the request will succeed unchanged (failures are never cached, so the retry is evaluated fresh).

treasury-capability-missing#

TREASURY_CAPABILITY_MISSING · 403 · Recoverable

The seller's Airwallex account is verified, but the treasury (transfers) capability required for API settlement has not been enabled by Airwallex. Nothing is wrong with the request body.

Fix. Check Settings → Verification for pending steps. Once the capability is enabled, retry with the same Idempotency-Key — the retry is evaluated fresh. If verification shows complete and this error persists, contact support with your requestId.

no-active-bma#

NO_ACTIVE_BMA · 409 · Not recoverable

The seller company has no active Business Model Agreement (BMA) with any publisher. POST /webhooks refuses to create a subscription, and catalog and fulfilment routes return empty results until at least one BMA is active. GET /whoami reports the same state as a warnings[] entry carrying this code.

Fix. Commercial, not technical. Sign a Business Model Agreement with a publisher in the console, then retry. Unlike CONTRACT_NOT_ACTIVE (one connection or contract on a specific order), this code means no agreement exists at all.


Catalog and sellability#

product-not-sellable#

PRODUCT_NOT_SELLABLE · 404 (immediate pull) / 422 (pre-order acceptance) · Not recoverable now, may resolve on its own

The SKU cannot be transacted right now: the product lifecycle is not live (draft, announced, discontinued, archived), the pre-order window has not opened or has already closed, or your company does not have the pre-order capability for a pre_order release.

details explains which, and when it changes:

KeyMeaning
reasonPREORDER_NOT_OPEN · PREORDER_CLOSED · PREORDER_DISABLED · LIFECYCLE_NOT_LIVE
launchPhaseEffective phase of the release (draft, announced, pre_order, available)
preorderStart, preorderEnd, releaseDateISO instants where known — the same skuId becomes sellable at these boundaries
recommendedActionwait_for_preorder_window · wait_for_release · request_preorder_capability · delist_sku

There is no successor product to switch to: a pre-order becomes its release in place, and release.available / sku.sellability_changed fire on the same skuId.

Fix. Branch on details.reason. For the wait_* actions keep the SKU listed but not purchasable and re-check GET /allocations (or subscribe to sku.sellability_changed) at the instant given. For delist_sku your catalog is stale — re-sync and delist. Do not charge buyers for SKUs in this state. Branch on code, not status alone — 404 can also mean the SKU is not visible to your company.

product-not-shared#

PRODUCT_NOT_SHARED · 404 · Not recoverable

The product exists, but your company has no active agreement that shares it: there is no connection with its Content Owner, or the agreement does not cover this product. GET /products/{productId} answers it on every contract date; GET and HEAD /products/{productId}/media/download answer it on contract date 2026-12-01 and later (earlier dates answer NOT_FOUND). A NOT_FOUND instead means the id is wrong or the product has no downloadable media.

Fix. Remove the product from your listing and do not retry with the same id. If you expected to sell it, ask the Content Owner to share it; GET /partners lists your agreements. A share that arrives later shows on GET /catalog/changes and in GET /products.

no-available-keys#

NO_AVAILABLE_KEYS · 409 · Not recoverable

Insufficient vendor inventory for the requested quantity. Nothing was pulled — orders are all-or-nothing. When the shortfall is your own allocation cap rather than vendor stock, you get ALLOCATION_EXCEEDED instead (see below).

If you have already charged the buyer, refund at your PSP. Avrix does not refund your buyer and has no mechanism to.

Fix. Gate on canFulfill from POST /orders/preview before charging, and treat cannotFullyFulfill: true (alias allOrNothingWillFail; deprecated name partialFulfillmentExpected) as "this order will 409" — it never means partial delivery. For high-contention drops, use a checkout hold or the reserve/commit flow. details.available gives the current count.

allocation-exceeded#

ALLOCATION_EXCEEDED · 409 · Not recoverable

Your allocation cap for this SKU is reached — the vendor may still hold stock, but your allocation has fewer keys remaining than the requested quantity. Nothing was pulled. details.remainingInAllocation gives the keys still available under your cap.

Allocation-cap shortfalls historically returned NO_AVAILABLE_KEYS; branch on ALLOCATION_EXCEEDED to distinguish "request a bigger allocation" from "vendor out of stock". NO_AVAILABLE_KEYS still fires for genuine vendor stock-outs.

Fix. Request a larger allocation with POST /allocations/requests ({ "allocationId": "<allocationId>", "requestedQuantity": n }), or reduce the quantity to the remaining headroom. The request is granted at once when the publisher has an automatic rule and the grant stays within its automatic limit, and otherwise waits for their review (GET /allocations/requests shows its state). Send an Idempotency-Key with the request so a retry does not file it twice. Retrying the order unchanged fails until the allocation is raised (details.recommendedAction is request_allocation_increase, and availability shows the same action).

order-reference-conflict#

ORDER_REFERENCE_CONFLICT · 409 · Not recoverable

POST /orders reused an orderReference that already belongs to a sale: its live keys on the same allocation do not equal the requested quantity, or its order was refunded or returned. A larger quantity would be a top-up (a silent second sale); a smaller one would hand back a subset of the original keys as if it were the order; a refunded order sold again would be a second sale under the first one's name. Avrix does none of these.

When the live keys under the reference equal the requested quantity, the same orderReference replays the original keys instead (no new inventory consumption, no second order.fulfilled). Only an order that never completed (a delivery Avrix compensated, with no key reaching the buyer) may be retried under the same reference.

Fix. Use a new orderReference (and a new Idempotency-Key) for a genuinely new sale. Investigate the prior delivery with GET /orders?orderReference=….

preorder-state-unavailable#

PREORDER_STATE_UNAVAILABLE · 503 · Recoverable

Preorder metadata could not be loaded. Retry after Retry-After (typically 5 seconds).


Pricing#

expected-unit-price-required#

EXPECTED_UNIT_PRICE_REQUIRED · 422 · Recoverable

expectedUnitPriceCents was omitted or invalid. The guard fails closed — there is no default.

Fix. Pass expectedUnitPriceCents (or expectedWholesaleUnitPriceCents) echoing unitPriceCents from your most recent preview. It must be a positive integer.

catalog-price-mismatch#

CATALOG_PRICE_MISMATCH · 409 · Recoverable

Under the API business model, expectedUnitPriceCents does not match the current territory catalog list price — or does not match the price snapshot bound by an active checkout hold. Preview and hold compare the echo only when you send it; POST /orders requires it.

Fix. Re-run POST /orders/preview for the same country and echo the new price. Then decide deliberately whether to proceed: if the price rose above what you sold at, you would be selling at a loss. This guard exists to make that a conscious decision.

Prevent it with a checkout hold, which binds the price for its TTL.

wholesale-price-mismatch#

WHOLESALE_PRICE_MISMATCH · 409 · Recoverable

Legacy contract code for non-API allocation price binding. Current Seller API partnerships use the API business model and should expect CATALOG_PRICE_MISMATCH instead when the echo does not match the territory catalog list price.

Fix. Re-run POST /orders/preview for the same country and echo the returned unitPriceCents as expectedUnitPriceCents.

catalog-price-not-set#

CATALOG_PRICE_NOT_SET · 422 · Not recoverable

No catalog price list entry exists for this SKU in the declared country. The SKU can be live and sellable in neighbouring countries: prices are set per country, not per region. details.recommendedAction is request_publisher_territory_pricing and details.readiness contains NO_TERRITORY_PRICING.

Find the sellable countries before checkout. GET /products/{productId}/pricing lists every country the SKU has a list price for. GET /availability?skuCode=…&countryCode=XX answers sellableInCountry with the blocking reason for one country (the same gates POST /orders applies). Hide the SKU in markets without a price rather than letting the buyer reach checkout.

Fix. Commercial. The vendor must set territory pricing for that country; until then exclude the SKU from that market.

invalid-catalog-price#

INVALID_CATALOG_PRICE · 422 · Not recoverable

The catalog list price is zero or negative. A data problem — escalate to the vendor.

currency-mismatch#

CURRENCY_MISMATCH · 422 · Recoverable

integrationOrderContext.currencyCode does not match the currency an active checkout hold froze with its price. Only the hold path returns this. On a plain POST /orders, a currency other than the one the country is priced in is refused by the order checks instead: the first that applies of FOOTPRINT_CURRENCY_NOT_DECLARED, CURRENCY_NOT_PERMITTED_BY_TERM and CURRENCY_NOT_PRICED_FOR_COUNTRY, in that order.

Fix. Re-read the hold, or create a new one in the currency you intend to sell in.

consumer-geo-mismatch-policy-refused#

CONSUMER_GEO_MISMATCH_POLICY_REFUSED · 422 · Not recoverable

The country you declared and the country the checkout evidence points at disagree, and the Content Owner's agreement refuses that.

Fix. Send the country the buyer is actually in, with a consumerIp that resolves there. This is the agreement's geo-mismatch policy rather than a platform rule: other Content Owners may allow the same sale, and the same one may allow it on a different SKU. Under the more common warn policy the sale proceeds and the disagreement is recorded on the transaction instead, where it lowers the evidence rank the sale settles at.

sales-channel-required#

SALES_CHANNEL_REQUIRED · 422 · Recoverable

integrationOrderContext.salesChannel is missing.

Fix. Declare which of your own surfaces the sale came through: web, mobile_app, partner_embed, or marketplace:<slug>. GET /whoami lists it under requiredDeclarations. Sandbox enforces this exactly as production does.

sales-channel-not-permitted#

SALES_CHANNEL_NOT_PERMITTED · 422 · Not recoverable

Your agreement's Commercial Schedule does not permit sales through this channel. Under the default, own storefronts only, any marketplace:<slug> is refused.

Fix. The grant is to sell to an end user through your own storefront. Listing a Key on a third-party marketplace is outside it, and an operator of a marketplace may hold the agreement only in respect of its own first-party storefront. Widening this is a countersigned amendment, not a settings change.

footprint-country-not-declared#

FOOTPRINT_COUNTRY_NOT_DECLARED · 422 · Recoverable

integrationOrderContext.salesCountryCode is not in your declared selling footprint.

Fix. Add the country in Commercial configuration. The error details carry a fixItUrl that links straight there. Your footprint is what the platform settles your sales against, so a country you have not declared cannot be sold into.

footprint-currency-not-declared#

FOOTPRINT_CURRENCY_NOT_DECLARED · 422 · Recoverable

The sale currency is not in your declared selling currencies.

Fix. Add the currency in Commercial configuration. The error details carry a fixItUrl that links straight there. Declaring a currency is not the same as being priced in it: the Content Owner's agreement still has to permit it and the title still has to carry a price, so this is the first of three checks rather than the only one.

When you declared no currency (a quote in the catalog's own currency) and that country is priced in a currency you do not sell in, the same code carries details.recommendedAction: request_publisher_territory_pricing and no fixItUrl: the remedy is the Content Owner pricing the country in one of your currencies (or the agreement permitting yours there), not your currency settings.

currency-not-priced-for-country#

CURRENCY_NOT_PRICED_FOR_COUNTRY · 422 · Recoverable

The declared currency is not the one the country is priced in (a country is sold in one currency), or the Content Owner no longer prices the country in that currency (details.reason currency_not_allowed_by_owner). The message names the currency.

Fix. Sell in the currency POST /orders/preview returns for that country. For currency_not_allowed_by_owner, the country is unsellable until the Content Owner prices it again. See Currency and FX.

currency-not-permitted-by-term#

CURRENCY_NOT_PERMITTED_BY_TERM · 422 · Not recoverable

Your agreement's Commercial Schedule does not permit sales in this currency. Under the default, each country's own currency only, any other currency is refused however the SKU is priced.

With partner access (GET /whoami accessByPublisher[].enforced: true), the currencies are the connection's access in force at the sale time: details.grantSource is "partner_access", details.reason is "currency_not_granted" (with details.permittedCurrencyCodes, where * is each country's priced currency) or the agreement's own-currency rule, and a currency the Content Owner removed from a date is listed under accessByPublisher[].pending until then.

Fix. Contact the Content Owner. With partner access they can propose the currency, and you accept it in the console or with POST /access/proposals/{id}/accept; without it, widening is a countersigned amendment to the agreement. GET /whoami reports what each agreement permits.

srp-mismatch-for-currency#

SRP_MISMATCH_FOR_CURRENCY · 422 · Recoverable

Deprecated, no longer returned (2026-10-09). It refused a sale in a second currency below the SRP converted at the reference rate. Second currencies are gone: a country is sold in the one currency it is priced in, and another currency is refused with CURRENCY_NOT_PRICED_FOR_COUNTRY. Keep handling the code if your client already does; it is no longer returned.

price-commitment-invalid#

PRICE_COMMITMENT_INVALID · 422 · Recoverable

The supplied priceCommitmentToken is not valid for this request.

Fix. Re-run POST /orders/preview and pass the new token, or use checkoutHoldId instead.

price-commitment-expired#

PRICE_COMMITMENT_EXPIRED · 422 · Recoverable

The preview price token has expired.

Fix. Re-run POST /orders/preview (or POST /orders/hold) before charging the buyer.


Territory#

sales-country-required#

SALES_COUNTRY_REQUIRED · 422 · Recoverable

No sales country was supplied. There is no default — the guard fails closed, because guessing a country would mean guessing a price and a tax treatment.

Fix. Pass countryCode on preview and integrationOrderContext.salesCountryCode on the order. The two are one declaration: a top-level countryCode is promoted into the context when that field is absent, and when both are sent they must agree (SALES_COUNTRY_MISMATCH).

sales-country-mismatch#

SALES_COUNTRY_MISMATCH · 422 · Recoverable

The request declared the sale country twice and the two disagree: top-level countryCode and integrationOrderContext.salesCountryCode are one declaration. Neither wins silently — a line priced for one country and settled for another is exactly what this refusal prevents.

Fix. Send either field, or both with the same value. details.countryCode and details.salesCountryCode echo what was received.

tax-declaration-required#

TAX_DECLARATION_REQUIRED · 422 · Recoverable

integrationOrderContext.salesTaxRatePercent or salesPriceGrossMinor is missing. JSON null counts as absent for both.

Fix. Declare what you charged the consumer and what tax was in it. The Content Owner's share is computed on the price net of that tax, so a sale that does not state it cannot be settled, and the refusal comes before a key is delivered rather than after. A zero rate is a declaration: send salesTaxRatePercent: 0 where no consumer tax applies. GET /whoami lists the required fields under requiredDeclarations, and sandbox enforces them exactly as production does.

vat-declaration-below-reference#

VAT_DECLARATION_BELOW_REFERENCE · 422 · Recoverable

The agreement for this SKU refuses sales whose declared VAT rate (integrationOrderContext.salesTaxRatePercent) is below the reference rate for the sale country (term vat_declaration_policy: refuse_below_reference). details.declaredRatePercent, details.expectedRatePercent and details.countryCode say by how much. Preview answers the same refusal, and nothing is pulled, reserved or charged.

Fix. Declare the rate you actually charge the buyer. If it really is lower (a reduced rate applies), ask the Content Owner to switch the term to warn; under warn the sale settles at your declared rate and carries vat_declared_rate_below_expected.

territory-not-allowed-for-sku#

TERRITORY_NOT_ALLOWED_FOR_SKU · 422 · Not recoverable

The buyer's country is not permitted for this SKU.

Fix. Gate checkout using allowedCountries on product detail, or GET /regions. Offer a different market SKU.

territory-not-granted#

TERRITORY_NOT_GRANTED · 422 · Not recoverable

Your agreement with this Content Owner does not grant this country. The grant is chosen per agreement when the Content Owner invites you: worldwide, a set of their regions, or your declared footprint on the day of the invite. Whatever the mode, it is frozen as a country list (or worldwide) when the agreement is sent, and this refusal fires whenever the buyer's country falls outside it. details.countryCode is the buyer's country, details.contractTermId the term, and details.grantMode says how the grant was defined (worldwide, regions or your declared footprint).

With partner access (GET /whoami accessByPublisher[].enforced: true), the grant is the connection's access in force at the sale time rather than the frozen list: the agreement seeded it, and the Content Owner may since have narrowed it or you may have accepted more. The refusal then carries details.grantSource: "partner_access", and accessByPublisher[].territories lists what is granted.

Fix. The Content Owner can propose more countries; you accept the proposal in the console or with POST /access/proposals/{id}/accept. Ask them rather than retrying. This is different from FOOTPRINT_COUNTRY_NOT_DECLARED, which you fix alone by declaring the country, and from REGION_LOCKED_FOR_CONTRACT, which narrows an agreement's territory rather than widening it: a country the grant includes that the Content Owner removed, not one that was never granted. It is also different from TERRITORY_NOT_ALLOWED_FOR_SKU, which is the SKU's own coverage rather than the agreement's grant.

territory-excluded-for-release#

TERRITORY_EXCLUDED_FOR_RELEASE · 422 · Not recoverable

The country is explicitly excluded for this release.

region-locked-for-contract#

REGION_LOCKED_FOR_CONTRACT · 422 · Not recoverable

The Content Owner locked this country under your agreement. The agreement's territory includes it, and this lock removes it.

A lock is restrictive only: it can refuse a sale the agreement would have allowed, and can never allow one the agreement refuses. That is why the Content Owner may set one without an amendment, and why every lock is visible to you before an order is refused. details.reason carries their own words, details.countryCode the country, and GET /whoami lists every lock that applies to you (accessByPublisher[].territories.locked). A lock may be set from a future date: until then it is listed under accessByPublisher[].pending and orders still go through, and from that moment they are refused. You are notified when a lock is set. Content Owners set partner locks on the partner page. Content Sellers can see them there and, when listed, under Commercial configuration as read-only.

Widening one is a conversation with the Content Owner, not a retry.

region-locked-for-sku#

REGION_LOCKED_FOR_SKU · 422 · Not recoverable

This title may not be sold in that country, whatever any agreement grants: a rating refusal, a platform restriction, a distribution carve-out. details.reason says which.

Different from TERRITORY_EXCLUDED_FOR_RELEASE, which is territorial configuration of the regional release, and from TERRITORY_NOT_ALLOWED_FOR_SKU, which means the country was never in the SKU's coverage. This one means the country IS in the coverage and someone chose to remove it for this title. Other titles in the same territory are unaffected, so offer a different SKU rather than a different market.

sku-region-unresolved#

SKU_REGION_UNRESOLVED · 422 · Not recoverable

The SKU has no territorial coverage configured. A data problem — escalate to the vendor.

activation-region-mismatch#

ACTIVATION_REGION_MISMATCH · 422 · Not recoverable

countryCode is outside this SKU's guaranteed activation set. Sale territory may still allow the sale, but the delivered key may not redeem in that country. Returned on preview, hold, reserve, orders and bulk (each line) under enforce_known, the platform default since 2026-09-24, or enforce_strict. A Content Owner that accepts the risk for its SKUs turns it into an advisory preview warning; a seller that opted into enforcement (whoami.capabilities.activationEnforceOptIn) is always refused. Responses carry details: skuId, countryCode, activationType, allowedCountries, and recommendedAction: restrict_sale_to_activation_countries. SANDBOX-ACTIVATION-LOCK-001 with countryCode: "US" rehearses it.

Fix. Gate checkout on activation.countries from GET /allocations or preview lines. Do not charge a buyer outside the guaranteed set.

activation-region-unknown#

ACTIVATION_REGION_UNKNOWN · 422 · Not recoverable

The SKU has no unarchived key-batch activation metadata, so coverage cannot be guaranteed. Returned only when activationPolicy is enforce_strict.

Fix. Ask the vendor to set batch activation (worldwide or an explicit country set), or keep the deployment on warn / enforce_known.


Consumer verification#

These apply to production keys where consumer geo enforcement is enabled. Check capabilities.consumerGeoEnforcementEnabled on GET /whoami.

consumer-ip-required#

CONSUMER_IP_REQUIRED · 422 · Recoverable

Production keys require integrationOrderContext.consumerIp.

Fix. Supply the buyer's public routable client IP — not your server's address, and not a private-range address.

consumer-ip-invalid#

CONSUMER_IP_INVALID · 422 · Recoverable

consumerIp is not a public routable IPv4 or IPv6 address. Private, loopback, and reserved ranges are rejected. A malformed address and a private, loopback, link-local or carrier-NAT address are refused when the request is parsed, on every surface (preview, hold, reserve, orders, bulk, keys/pull, keys/export), whether or not the buyer-network evaluation runs; details.issues names the field.

The same code refuses a store-server address. A production key rejects a declared consumerIp that equals the address calling the API, or that matches an entry on the key's IP allowlist. At buyer verification level declared_ip this applies on preview, hold, reserve, orders and bulk; on the checkout-confirmation levels it applies to the address that completed the checkout pixel. Sandbox keys accept it.

Fix. Extract the real client address from your proxy headers, correctly — behind a load balancer, the immediate peer address is your own infrastructure.

consumer-geo-mismatch#

CONSUMER_GEO_MISMATCH · 422 · Recoverable

The country derived from consumerIp does not match salesCountryCode.

Fix. Ensure the declared sales country reflects where the buyer actually is.

consumer-ip-high-risk#

CONSUMER_IP_HIGH_RISK · 422 · Not recoverable

The address is a VPN, hosting provider, Tor exit, or public proxy.

consumer-geo-unavailable#

CONSUMER_GEO_UNAVAILABLE · 503 · Recoverable

The geo database is temporarily unavailable. Retry with the same Idempotency-Key after Retry-After (typically 5 seconds).

country-restricted#

COUNTRY_RESTRICTED · 422 · Not recoverable

Sales are not available for this location.

Fix. Do not offer checkout for that market. Use GET /allocations and product territory fields to gate the storefront.

consumer-geo-attest-required#

CONSUMER_GEO_ATTEST_REQUIRED · 422 · Recoverable

This catalog requires confirming the buyer’s network from the checkout page.

Fix. POST /geo/attest with your API key, load the returned pixelUrl in the buyer’s browser (or POST /geo/attest/{attestId}/complete from that page), then retry the commercial call with consumerGeoAttestId. Do not complete the pixel from your store server. This check runs after the order admission (country, price, footprint, currency, channel), so any refusal you can fix in the request is reported first; the confirmation is spent only when a commit delivers the key, never by a refused commit.

consumer-geo-attest-expired#

CONSUMER_GEO_ATTEST_EXPIRED · 422 · Recoverable

The confirmation you sent as consumerGeoAttestId is older than its window: an attest is completable and usable for 10 minutes from POST /geo/attest. details.expiresAt says when it lapsed.

Fix. Mint a new one, load pixelUrl in the buyer's browser, then retry.

consumer-geo-attest-consumed#

CONSUMER_GEO_ATTEST_CONSUMED · 422 · Recoverable

The confirmation was already spent on another order (details.consumedOrderReference). One confirmation covers one order; only a retry of the same orderReference may reuse it.

Fix. Mint a new confirmation for this order.

consumer-geo-attest-invalid#

CONSUMER_GEO_ATTEST_INVALID · 422 · Recoverable

consumerGeoAttestId is unknown, was minted by another API key or account, or the pixel was completed from your store server rather than the buyer's browser (the completion itself is refused with this code, and the attest stays incomplete).

Fix. Mint the confirmation with the key that places the order, and load the pixel from the checkout page in the buyer's browser.

consumer-risk-high#

CONSUMER_RISK_HIGH · 422 · Not recoverable

This Content Owner scores each confirmed checkout and refuses orders whose risk score reaches their threshold. The score itself is never returned.

Fix. Do not deliver. Offer the buyer another payment or verification path; a new checkout confirmation from a different network may score differently. Under a Content Owner whose action is flag only, the same outcome arrives as a riskWarning on a 200 instead. See Buyer verification levels.

consumer-risk-unavailable#

CONSUMER_RISK_UNAVAILABLE · 503 · Recoverable

The buyer risk assessment this Content Owner requires could not be completed (provider unavailable, or the confirmation could not be scored).

Fix. Retry after Retry-After with the same Idempotency-Key and the same consumerGeoAttestId; the confirmation is not spent by a failed assessment. If it persists, treat the order as not placed and let the buyer try again later.

location-blocked#

LOCATION_BLOCKED · 403 · Not recoverable

Access is not available from the current location.

Fix. Call the API from an allowed network. This is an access control on your integration egress, not a buyer-checkout error.


Checkout holds#

checkout-hold-disabled#

CHECKOUT_HOLD_DISABLED · 412 · Recoverable

Checkout hold is not enabled for this deployment or account.

Fix. Check capabilities.checkoutHoldEnabled on GET /whoami before calling hold endpoints, and fall back to preview gating alone. See Checkout holds.

hold-exists#

HOLD_EXISTS · 409 · Recoverable

A live checkout hold already covers this orderReference for your account. A second hold for one cart is never granted and takes no capacity; details.holdId and details.expiresAt name the hold that does.

Fix. Reuse details.holdId on POST /orders, or DELETE /orders/hold it first and hold again. A different cart needs a different orderReference.

sold-out#

SOLD_OUT · 409 · Recoverable

The checkout-hold (or hot-drop reservation) capacity for this allocation is taken: other live holds already cover every sellable key. details.remaining is the capacity left, which may be below your quantity. Nothing was held.

Fix. Hold a smaller quantity, or retry after holds expire or are released. Check GET /availability for inventoryAvailable and heldQuantity before holding again.

store-unavailable#

STORE_UNAVAILABLE · 503 · Recoverable

The hold store could not take the hold (the counter was not ready or the store did not answer). Nothing was held.

Fix. Retry the same request after Retry-After with the same Idempotency-Key. If it persists, place the order without a hold (POST /orders); the hold is optional.

sku-not-found#

SKU_NOT_FOUND · 404 · Not recoverable

The skuId or skuCode does not exist, or it is not shared with your account, so there is nothing to quote or hold.

Fix. Use a SKU from GET /catalog/snapshot or GET /allocations. Codes are exact matches.

allocation-not-found#

ALLOCATION_NOT_FOUND · 404 · Not recoverable

You have no allocation for this SKU (or the allocationId is not yours), so it cannot be quoted or held.

Fix. Check GET /allocations. Ask the publisher for an allocation, or use a SKU you hold one for.

allocation-inactive#

ALLOCATION_INACTIVE · 404 · Not recoverable

You have no active allocation for this SKU: it was never granted to you, or the grant is paused, revoked or expired. Preview cannot tell those apart, so both answer 404.

On contract date 2026-12-01 and later, preview answers a paused or otherwise inactive allocation as POST /orders does: 400 BAD_REQUEST with details.allocationResolve NO_ACTIVE_ALLOCATION and the same message, keeping details.previewError and details.allocationStatus. Earlier dates and unpinned requests keep this 404.

Fix. Check GET /allocations for the SKU and its status. Ask the publisher for an allocation, or wait for a paused one to be reactivated; nothing in the request can change that.

key-not-returnable#

KEY_NOT_RETURNABLE · 409 · Not recoverable

POST /refunds or POST /keys/return named a key that is not in a returnable state: it was already returned or refunded (a retry of a refund that succeeded), it was never delivered, or it was redeemed and its business model does not refund redeemed keys (only revenue share does). details.keyId, details.keyStatus and details.businessModel name it. The request is all-or-nothing, so no key in it was changed.

POST /returns answers this code with 422 instead, and details.reason says why the Content Owner cannot take the keys back (for example claim_window_expired or model_not_supported_wholesale).

Fix. Do not retry the same keys. Ask POST /refunds/preview first: it answers per key with eligible, reason and keyStatus. Check GET /refunds?orderReference= or GET /orders/{orderId} for what is already refunded; refund only the keys that are still live.

A refund that answered 5xx changed nothing: the keys, the sale and its refund completion commit together or not at all. Retry it with the same Idempotency-Key; it does not answer KEY_NOT_RETURNABLE for that reason.

refund-quantity-exceeds-live-keys#

REFUND_QUANTITY_EXCEEDS_LIVE_KEYS · 409 · Not recoverable

POST /refunds with quantity, orderReference and strict: true asked for more keys than are still live under that reference. Nothing was refunded. details.requested and details.liveKeys give both numbers.

Fix. Refund details.liveKeys or fewer, or send the request without strict to refund the live keys and see the shortfall in skipped.

refund-window-expired#

REFUND_WINDOW_EXPIRED · 422 · Not recoverable

POST /refunds with type: "refund", or POST /keys/return, was sent after the Content Owner's refund window (refundPolicy.windowDays on GET /allocations and GET /products/{productId}). details.keys[] lists each late key with soldAt, windowDays and refundableUntil. Nothing was refunded.

Fix. Handle the buyer's claim under your own terms, or ask the Content Owner. A chargeback (type: "chargeback") is never windowed: the bank decides it.

refund-limit-reached#

REFUND_LIMIT_REACHED · 422 · Not recoverable

POST /refunds or POST /keys/return would take an allocation over its refund limit. Refunds plus chargebacks on one allocation are limited to 20% of the keys sold on it in the last 30 days, and never fewer than 5 keys. details gives the figures: allocationId, windowDays, soldInWindow, refundedInWindow, refundLimit and requested. Nothing was refunded, and the keys stay sold.

Fix. Do not retry: the answer stays the same until earlier refunds leave the 30-day window or more keys are sold. If the refunds are genuine, contact Avrix support with the requestId to have them reviewed.

hold-not-found#

HOLD_NOT_FOUND · 404 · Recoverable

The checkoutHoldId was unknown, expired, or already consumed. POST /orders no longer fails on this: a lapsed hold is dropped and the commit proceeds as a plain order (the response carries checkoutHold.committedWithoutHold: true). DELETE /orders/hold no longer answers it either: a release is idempotent and answers 200 with released: false for a hold that is already gone. The code still surfaces from GET /orders/hold/{holdId} (details.holdState: released, consumed, or not_found), and from a replay of POST /orders/hold with the Idempotency-Key of a hold that is no longer live: details.holdState says released, consumed or expired, and a new Idempotency-Key creates a new hold.

Fix. Nothing on the commit path. Elsewhere, create a new hold with POST /orders/hold or proceed from a fresh preview.

hold-mismatch#

HOLD_MISMATCH · 422 · Recoverable

The order body does not match the hold — SKU, quantity, or orderReference differs.

Fix. Reuse the same SKU, quantity, and orderReference that were bound when the hold was created, or create a new hold for the corrected request.

expected-price-conflict#

EXPECTED_PRICE_CONFLICT · 422 · Recoverable

On POST /orders/hold, the expected price echo did not match the bindable catalog or wholesale price for the request.

Fix. Re-run POST /orders/preview for the same country and pass the returned price fields on the hold request.


Hot-drop reservations#

hot-drop-not-enabled#

HOT_DROP_NOT_ENABLED · 412 · Recoverable

The allocation is not in hot-drop mode. POST /orders/reserve is a no-op for that allocation.

Fix. Fall back to Profile B — call POST /orders directly. See Hot drop.

reservation-gone#

RESERVATION_GONE · 410 · Recoverable

The hot-drop reservation was not found, expired, or already consumed.

Fix. Call POST /orders/reserve again, then commit within the new TTL. Do not invent a new idempotency key for a commit you believe already succeeded — check GET /orders first. If the order is there (GET /orders?orderReference=… with the reservation's reference), the earlier commit succeeded and its response was lost: store the order's orderId and take the keys from POST /orders/recover-keys; do not reserve again.

allocation-not-available#

ALLOCATION_NOT_AVAILABLE · 409 · Recoverable

The hot-drop reservation you are committing points at an allocation that is no longer active or no longer in hot-drop mode (the publisher changed the grant between reserve and commit). The reservation is released.

Fix. Preview again and place the order through the normal POST /orders path; if the SKU is gone from GET /allocations, refund the buyer at your PSP.

quantity-invalid#

QUANTITY_INVALID · 422 · Recoverable

POST /orders/reserve received a quantity that is not a positive integer within the hot-drop per-reservation cap.

Fix. Send an integer quantity ≥ 1 and at most the maxFulfillableQuantity the preview reported.

reservation-commit-in-progress#

RESERVATION_COMMIT_IN_PROGRESS · 409 · Recoverable

Another commit for this reservation is already running.

Fix. Retry shortly with the same body and idempotency key. Do not open a second reservation for the same payment.

reservation-extend-exhausted#

RESERVATION_EXTEND_EXHAUSTED · 409 · Not recoverable

The reservation was already extended once; further extensions are not allowed. (Internal ALREADY_EXTENDED maps to this partner-facing code.)

Fix. Commit before the current TTL expires, or re-reserve if the slot is gone.

order-not-extendable#

ORDER_NOT_EXTENDABLE · 409 · Not recoverable

POST /orders/{orderId}/extend was called with an order readable id (ord_…) that names an order already placed. Only a hot-drop reservation can be extended: its reservationId (UUID) from POST /orders/reserve is the orderId that route takes. details.orderId and details.status name the order. Nothing was changed.

Fix. Extend the reservation by its reservationId, or leave the order alone: a placed order has no TTL.


Capability gates#

feature-disabled#

FEATURE_DISABLED · 403 · Not recoverable

A capability required by the request is off for this environment. Check capabilities on GET /whoami and use only features that are enabled for your key. backorderOnUnavailable: true returns this code only while capabilities.backorderEnabled is false (backorders are on by default; Avrix switches them off platform-wide only during an incident).

Fix. Do not retry with the same request until the capability is enabled for your environment. Prefer the documented key-delivery path (deliveryMode: "key"). Omit backorderOnUnavailable until backorderEnabled is true.

backorder-not-allowed#

BACKORDER_NOT_ALLOWED · 403 · Not recoverable

backorderOnUnavailable: true was sent, but the Content Owner of this grant has opted out of customer-order backorders.

Fix. Omit backorderOnUnavailable for this Content Owner's SKUs and refund the buyer on NO_AVAILABLE_KEYS, or ask the Content Owner to accept backorders. Do not treat this as a preorder.

order-not-ready#

ORDER_NOT_READY · 409 · Recoverable

POST /orders/{orderId}/fulfill was called before keys were available for the pending quantity. Wait for order.ready.

Fix. Subscribe to order.ready, then retry fulfill with the same Idempotency-Key only after that event (or after GET /orders/{orderId} shows ready).

export-expired#

EXPORT_EXPIRED · 410 · Not recoverable

The catalog export artifact TTL has elapsed. The signed URL is no longer issued.

Fix. Call POST /catalog/exports again and poll the new exportId. Do not retry the expired id.

already-activated#

ALREADY_ACTIVATED · 409 · Not recoverable

A fulfilment management action was rejected because the fulfilment is already in a terminal activated/redeemed state.

Fix. Do not call regenerate after activation. Issue a new order if the business process requires a fresh fulfilment.

expired#

EXPIRED · 409 · Not recoverable

A hosted fulfillment has passed its original expiry. Regeneration is rejected before changing the existing fulfillment or creating another link.

Fix. Do not retry regeneration for this fulfillment. Resolve the buyer order through your support process. Rotation of a compromised link must happen before its original expiry; rotation preserves that expiry.

regenerate-not-supported#

REGENERATE_NOT_SUPPORTED · 422 · Not recoverable

The fulfilment provider does not support regenerate for this fulfilment.

Fix. Check the provider on the fulfilment. Do not assume regenerate is available for every delivery path.

keyless-issuance-failed#

KEYLESS_ISSUANCE_FAILED · 503 · Recoverable

Fulfilment issuance failed after inventory pull. Orphaned keys are compensated and the idempotency claim is released so a retry can heal.

Fix. Retry with the same Idempotency-Key after Retry-After (typically 30 seconds). Do not create a second order against the same payment.


Capabilities and environment#

sandbox-magic-value-rejected#

SANDBOX_MAGIC_VALUE_REJECTED · 422 · Not recoverable

A sandbox fixture — a magic SKU, sandbox_order_* reference, or sandbox_pay_* payment reference — was used with a production key.

Fix. Replace test fixtures with real values. See Sandbox to production.

sandbox-key-required#

SANDBOX_KEY_REQUIRED · 422 · Not recoverable

A sandbox-only operation or option was called with a production key: GET /sandbox/certification, or POST /webhooks/{id}/test with an eventType other than test.ping or with a challenge. details.field names the option on the test-fire call. Nothing was queued.

Fix. Call it with a sandbox key. A production key can still send a plain test.ping (no body).

sandbox-environment-unavailable#

SANDBOX_ENVIRONMENT_UNAVAILABLE · 503 · Recoverable

Your store runs in its own isolated sandbox environment, and that environment is being prepared or repaired. Sandbox requests are not sent to another environment in the meantime. The body carries details.retryable: true, details.retryAfterSeconds (30) and a Retry-After header. Production keys are never affected.

Fix. Retry after Retry-After (also in details.retryAfterSeconds). Reuse the same Idempotency-Key for writes. If it persists for more than a few minutes, contact support with the requestId. See Sandbox.

sandbox-environment-paused#

SANDBOX_ENVIRONMENT_PAUSED · 503 · Recoverable

Avrix paused writes to your isolated sandbox environment while it is repaired. Writes (orders, holds, refunds, webhook changes and other mutations) answer this code; reads keep working. The body carries details.retryable: true and details.retryAfterSeconds, and the response sets Retry-After.

Fix. Keep reading as usual and retry the write later with the same Idempotency-Key. Avrix resumes writes when the repair is done.

sandbox-scenario-unavailable#

SANDBOX_SCENARIO_UNAVAILABLE · 422 · Not recoverable

The request named a stateful fault scenario in X-Avrix-Sandbox-Simulate that cannot run here: either your store is not yet on its isolated sandbox environment (scenarios keep state per environment), or the scenario belongs to another route (partial_cart runs on POST /orders/bulk, sold_out_after_hold on POST /orders/hold). details.value names the scenario. Nothing was changed.

Fix. Send the scenario to its route, or use a stateless X-Avrix-Sandbox-Simulate value until your store runs in its isolated environment. See Sandbox.

sandbox-simulate-unknown#

SANDBOX_SIMULATE_UNKNOWN · 422 · Not recoverable

Contract date 2026-12-01 and later, sandbox keys only. X-Avrix-Sandbox-Simulate carried a value this operation does not honour. details.reason is unknown_value (not a simulate value at all, a misspelling for example) or not_honoured_here (a real value that belongs to another operation). details.value echoes what you sent and details.honoured lists the values this operation accepts. Nothing was done. On earlier contract dates the header is ignored in this case, and a production key's header is ignored on every date.

Fix. Send one of the values in details.honoured, or drop the header. Each operation's values are declared on its X-Avrix-Sandbox-Simulate parameter in the OpenAPI document. See Sandbox.

sandbox-isolated-environment-required#

SANDBOX_ISOLATED_ENVIRONMENT_REQUIRED · 422 · Not recoverable

Sandbox keys on the shared sandbox only. The call would change data that every store on the shared sandbox reads, so it is refused there. Nothing was changed. details.operation names the call and details.sandboxMode is shared. Two kinds of call answer it:

  • The sandbox controls that change shared data, on every contract date: POST /sandbox/reset, POST /sandbox/promotions/deals/{responseId}/window, and an approval through POST /sandbox/allocations/requests/{requestId}/resolve (a decline still works).
  • PUT /me/footprint and PATCH /allocations/{id}, on contract date 2026-12-01 and later only. On earlier contract dates these still run on the shared sandbox.

Production keys are never affected.

Fix. Make the call once your store runs in its own isolated sandbox environment, where it changes only your data. GET /sandbox/certification reports data.environment.mode. See Sandbox.

catalog-resync-required#

CATALOG_RESYNC_REQUIRED · 409 · Not recoverable by retrying

The change-feed request (GET /catalog/changes or GET /availability/changes) cannot continue from the position it sent; details.field names cursor or since. There are two causes:

  • Retention (details.reason is retention_expired, contract date 2026-12-01 and later, production and sandbox keys): the position is older than the feed's retention of at least 30 days, and changes after it were deleted. Earlier dates serve the rows still kept after the position, without this signal.
  • Sandbox move (sandbox keys only, no details.reason): your store moved to its isolated sandbox environment, and the request used a cursor from the shared sandbox feed, or a since from before the move. Product, SKU and allocation ids changed with the move; public sandbox fixture codes such as SANDBOX-ALWAYS-001 did not.

Fix. Take a fresh GET /catalog/snapshot and continue from its meta.changesCursor and meta.availabilityCursor. After a sandbox move, also replace the sandbox product, SKU and allocation ids you stored. Do not retry the old cursor. See Lists and pagination.


Rate limiting and server errors#

rate-limit-exceeded#

RATE_LIMIT_EXCEEDED · 429 · Recoverable

You exceeded the rate limit for this endpoint class. Sandbox limits fail closed: if the rate-limit store is unavailable the request is rejected rather than allowed through, so a burst of 429 responses during an Avrix incident is expected behaviour, not a bug in your client. Production fair-use limits fail open, and refuse only once enforcement is on (see Rate limits).

Fix. Wait for Retry-After seconds. Longer term: cache catalog reads and honour ETag, since conditional requests returning 304 do not consume budget. Do not call checkout-authority endpoints during browsing.

hot-path-timeout#

HOT_PATH_TIMEOUT · 504 · Recoverable

The database did not answer within the hot-path budget. When the database itself stopped the statement, nothing committed; when the answer was lost on the way back, the order may have committed. The response cannot tell the two apart, so treat the outcome as unknown.

Fix. Retry with the same Idempotency-Key, body and orderReference after Retry-After (typically 1 second): a committed order replays, an uncommitted one is placed. Do not refund on this code alone. See A 5xx after you charged the buyer.

key-decrypt-failed#

KEY_DECRYPT_FAILED · 503 · Recoverable

Key material could not be decrypted after a successful pull attempt.

Fix. Retry with the same Idempotency-Key after Retry-After (typically 5 seconds). If it persists, contact support with the requestId.

key-not-replaceable#

KEY_NOT_REPLACEABLE · 409 · Not recoverable

POST /orders/{orderId}/keys/{keyId}/replace cannot replace this key: it is no longer delivered to the order (returned, refunded, or already replaced by another key). details.keyId names the key. Nothing was pulled or charged.

Fix. Read the order with GET /orders/{orderId}: replacements[] shows what happened to the key and POST /orders/recover-keys returns the keys the order holds now. Replace one of those, or refund the buyer.

billing-record-failed#

BILLING_RECORD_FAILED · 503 · Recoverable

The order pull completed inventory work but the commercial sale record could not be written. Keys are compensated (not delivered); nothing was billed.

Fix. Retry with the same Idempotency-Key after Retry-After. If it persists, escalate with the requestId.

service-unavailable#

SERVICE_UNAVAILABLE · 503 · Recoverable

A required backing store is temporarily unavailable: the database or its API layer (a schema reload, a dropped or refused connection, an exhausted connection pool) or another dependency such as the hot-drop reservation store. Every Seller API route answers these the same way, with Retry-After and details.retryable: true; a database that answers too slowly is 504 HOT_PATH_TIMEOUT instead. X-Avrix-Sandbox-Simulate: service_unavailable rehearses it.

Fix. Retry after Retry-After, then with exponential backoff. For writes, reuse the same Idempotency-Key and orderReference; do not refund on this code alone. Check the status page for an ongoing incident.

internal-error#

INTERNAL_ERROR · 500 · Recoverable

An unexpected server error.

Fix. Retry with exponential backoff, reusing the same Idempotency-Key for writes. If it persists, check the status page, then contact support with the requestId.


Webhook registration#

Webhook URL checks on POST /webhooks and PATCH /webhooks/{id} surface as VALIDATION_FAILED (422, schema issues on url) or BAD_REQUEST (400, repository guard messages such as "URL must use https://" / public-host requirements). Delivery-time SSRF guards use internal WEBHOOK_URL_* strings and are not returned as partner envelope codes.

webhook-endpoint-limit-reached#

WEBHOOK_ENDPOINT_LIMIT_REACHED · 409 · Not recoverable

POST /webhooks refused a new endpoint because the company already has 16 (active and disabled endpoints count; deleted ones do not). For a sandbox key the limit applies per key. details.limit is the limit and details.current the number you have. Nothing was created. This code is returned on contract date 2026-12-01 and later; earlier dates register the endpoint as before. Endpoints that already exist above the limit keep working.

Fix. Delete an endpoint you no longer use (DELETE /webhooks/{id}), or subscribe an existing endpoint to more events with PATCH /webhooks/{id}. One endpoint can take every event with *, or a whole family with a wildcard such as order.*.


OAuth#

Optional Seller API OAuth (POST /api/seller/oauth/token) returns the standard flat Avrix error envelope — not the RFC 6749 {"error": "..."} body. Mapping from the RFC 6749 concepts:

HTTPcodeRFC 6749 analogueWhenAction
422VALIDATION_FAILEDinvalid_request / unsupported_grant_typeBody fails schema: missing field, grant_type is not client_credentials, or client_id is not a UUIDFix the request body
401INVALID_CLIENTinvalid_client / invalid_grantUnknown client_id, wrong client_secret, expired/revoked/archived key, or the company is revoked/deleted/not a sellerVerify credentials; rotate or replace the key
429RATE_LIMIT_EXCEEDEDslow_downPer-source-IP or per-client_id mint throttleBack off per Retry-After
501NOT_IMPLEMENTED—Token minting is disabled on this deploymentFall back to the long-lived key Bearer
503SERVICE_UNAVAILABLE—Token store unavailableRetry with backoff

Tokens are opaque avrix_oat_* strings; an expired or unknown token on a v1 route fails like any bad Bearer credential (401 UNAUTHORIZED). Full endpoint contract: OAuth tokens. Prefer scoped API keys documented in Authentication.

invalid-client#

INVALID_CLIENT · 401 · Not recoverable without new credentials

The OAuth token mint rejected the client: unknown client_id, wrong client_secret, an expired/revoked/archived key, or the owning company is revoked, deleted, or not a seller.

Fix. Verify the client_id / client_secret pair against an active API key. If the key was rotated or revoked, mint credentials from the replacement key.

not-implemented#

NOT_IMPLEMENTED · 501 · Not recoverable on this deployment

OAuth token minting is disabled on this deployment.

Fix. Authenticate with the long-lived API key Bearer instead (see Authentication).


Getting help#

Include in every support request: the requestId, the code, the endpoint and method, the approximate timestamp with timezone, your orderReference if applicable, and what you expected.

Do not include your API key, key plaintext, or webhook secret.

Code example#

# Retry manually on 429 / 5xx — read Retry-After from response headers
curl -s -D - "$AVRIX_BASE_URL/api/seller/v1/whoami" \
  -H "Authorization: Bearer $AVRIX_API_KEY" | head

What links here

Published guides that link to this page.

Search docs

Search documentation…