Every Seller API error code, what causes it, whether retrying is safe, and how to fix it.
Error recovery overview#
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:
- Your selling footprint: the country (
FOOTPRINT_COUNTRY_NOT_DECLARED), then the currency (FOOTPRINT_CURRENCY_NOT_DECLARED). - What your agreement or partner access grants: the territory (
TERRITORY_NOT_GRANTED), then the currency (CURRENCY_NOT_PERMITTED_BY_TERM). - Access to the product: the share, exclusions and your allocation.
- Territory: release exclusions, SKU and contract region locks, restricted countries.
- The catalog price (
CATALOG_PRICE_NOT_SET, or a price echo that does not match). - The priced currency (
CURRENCY_NOT_PRICED_FOR_COUNTRY). - The sales channel (
SALES_CHANNEL_NOT_PERMITTED). - 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):
{
"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"
}
| Field | Use |
|---|---|
code | Branch on this. Stable across releases. Never parse message. |
message | Human-readable. Wording may change; do not match on it. |
recoverable | Whether the condition may resolve on retry. Not the same as "safe to retry blindly". |
hint | Short remediation guidance. |
doc_url | Deep link to the section on this page. |
requestId | Log this. Quote it in every support request. |
timestamp | ISO-8601 time the error was formed. |
details | Structured 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. |
error | Deprecated. 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:
consoleAction | Console page | Typical codes / decisionCode |
|---|---|---|
review_partner_contracts | Partners → Contracts | CONTRACT_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_allocations | Commerce → Allocations | ALLOCATION_EXCEEDED, NO_AVAILABLE_KEYS; ALLOCATION_PAUSED, ALLOCATION_REVOKED |
manage_api_keys | Settings → API keys | INSUFFICIENT_SCOPE, IP_NOT_ALLOWED, ALLOWLIST_REQUIRED, KEY_ENVIRONMENT_MISMATCH, PRODUCTION_ACCESS_NOT_APPROVED |
complete_kyb | Settings → KYB | KYB_NOT_VERIFIED, TREASURY_CAPABILITY_MISSING |
top_up_wallet | Finance → Wallet | INSUFFICIENT_WALLET_BALANCE, PAYMENT_NOT_CLEARED |
review_partner_catalog | Catalog → Products | PRODUCT_NOT_SELLABLE, TERRITORY_*, SKU_REGION_UNRESOLVED, ACTIVATION_REGION_*, CATALOG_PRICE_NOT_SET, INVALID_CATALOG_PRICE; SKU_SHARE_MISSING, SKU_SHARE_SUSPENDED |
review_commercial_settings | Settings → Commercial | FOOTPRINT_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#
| Class | Retry? | How |
|---|---|---|
5xx | Yes | Exponential backoff, same Idempotency-Key |
429 | Yes | Wait for Retry-After |
409 IDEMPOTENCY_REQUEST_IN_FLIGHT | Yes | Wait for Retry-After |
| Timeout, no response | Yes | Same key, same body. See unknown outcome |
409 NO_AVAILABLE_KEYS | No | Deterministic |
409 ALLOCATION_EXCEEDED | No | Request a larger allocation (POST /allocations/requests) or lower the quantity |
422 | No | Fix the request first |
401, 403 | No | Credential 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:
- Retry with the same
Idempotency-Key, the same body and the sameorderReference, 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. - Still no answer? Look it up.
GET /orders?orderReference=shows whether keys were delivered. - Keys delivered but you never received them? POST /orders/recover-keys returns them.
- 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:
| Signal | Meaning |
|---|---|
403 + JSON envelope with code | Authorization problem — see the codes below |
403 + HTML body, no X-Request-Id | Edge challenge — your traffic profile tripped platform protection |
429 + JSON + Retry-After | API 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-01and later (pinned withX-Avrix-Api-Version, ornext), every operation answers a missing scope with this code.details.requiredScopeslists every scope the operation accepts, preferred first; holding any one of them is enough.details.missingScopenames the preferred scope.details.scopeModeisanyOf, oranyfor the few operations that accept any Seller API scope (requiredScopesthen lists them all). A key with no scopes at all also carriesdetails.reason: "scopes_required". On earlier dates the same refusal isFORBIDDEN. - On every contract date,
POST /keysreturns this code when the calling key cannot give the new key the scopes it would receive (includeFinanceScopewithoutseller:finance:readon 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.accessCode | Status and code | Meaning | What to do |
|---|---|---|---|
AMENDMENT_NOT_FOUND, AMENDMENT_NOT_ACCESS, AMENDMENT_SELF_ACCEPT_FORBIDDEN, AMENDMENT_SELF_DECLINE_FORBIDDEN | 404 NOT_FOUND | No open access proposal with this id is addressed to you | Re-read GET /access/proposals; use only ids it lists |
AMENDMENT_NOT_PROPOSED | 409 CONFLICT | The proposal was already answered, or the vendor withdrew it | Re-read GET /access/proposals and GET /whoami (accessByPublisher); do not retry |
AMENDMENT_TERM_NOT_ACTIVE | 409 CONFLICT | The 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_FOUND | 409 CONFLICT | The agreement it amends no longer exists | Ask the vendor for a new proposal |
ACCESS_TERMS_NOT_ACCEPTED | 409 CONFLICT | Your company has not accepted the updated platform terms that partner access needs | Accept them in the console, then answer again |
ACCESS_FX_NOT_COVERED | 422 VALIDATION_FAILED | Accepting 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_ALLOWED | 422 VALIDATION_FAILED | Accepting a currency the vendor no longer allows there | Ask 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:
| Key | Meaning |
|---|---|
reason | PREORDER_NOT_OPEN · PREORDER_CLOSED · PREORDER_DISABLED · LIFECYCLE_NOT_LIVE |
launchPhase | Effective phase of the release (draft, announced, pre_order, available) |
preorderStart, preorderEnd, releaseDate | ISO instants where known — the same skuId becomes sellable at these boundaries |
recommendedAction | wait_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 throughPOST /sandbox/allocations/requests/{requestId}/resolve(a decline still works). PUT /me/footprintandPATCH /allocations/{id}, on contract date2026-12-01and 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.reasonisretention_expired, contract date2026-12-01and 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 acursorfrom the shared sandbox feed, or asincefrom before the move. Product, SKU and allocation ids changed with the move; public sandbox fixture codes such asSANDBOX-ALWAYS-001did 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:
| HTTP | code | RFC 6749 analogue | When | Action |
|---|---|---|---|---|
| 422 | VALIDATION_FAILED | invalid_request / unsupported_grant_type | Body fails schema: missing field, grant_type is not client_credentials, or client_id is not a UUID | Fix the request body |
| 401 | INVALID_CLIENT | invalid_client / invalid_grant | Unknown client_id, wrong client_secret, expired/revoked/archived key, or the company is revoked/deleted/not a seller | Verify credentials; rotate or replace the key |
| 429 | RATE_LIMIT_EXCEEDED | slow_down | Per-source-IP or per-client_id mint throttle | Back off per Retry-After |
| 501 | NOT_IMPLEMENTED | — | Token minting is disabled on this deployment | Fall back to the long-lived key Bearer |
| 503 | SERVICE_UNAVAILABLE | — | Token store unavailable | Retry 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.
Related#
- Order lifecycle — failure modes in flow context
- Authentication — credential troubleshooting
- Order preview — catch pricing and availability errors before you charge
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