| Mandate refusals | spend cap, scope, expiry, ownership; an agent with no mandate is refused at confirm (422 mandate_invalid) | The buyer’s limits said no. Surface to the buyer; do not retry — the answer won’t change. |
Hosted checkout (409 hosted_checkout_required, details.checkoutUrl) | the shop sells only through its own checkout page, so Alyte cannot reserve or pay there | Send the buyer to details.checkoutUrl. Do not retry the reserve. |
| Catalog refusals | not on sale yet, quantity cap, geo/scheme restriction, sold out | Terminal for this request. not_yet_on_sale includes a retryAfter — schedule, don’t poll. |
Validation (400) | float prices, malformed bodies | Fix the request. Money is integer minor units, always. |
Auth (401/403) | expired token, missing scope, revoked key | Re-authenticate or request the right scope. Revocation is server-side and immediate. |
Verification required (403 step_up_required) | a merchant-attested buyer session tried to create or widen spending authority | Not a failure. The buyer must confirm a code sent to their email; the authorize page does this itself. |
Sign-in token spent (401 link_invalid) | a redeem link or session-token exchange used twice, or after 15 minutes | Terminal for that token. Mint a new session. A refused exchange from an unregistered origin (403) does not spend the token. |
Browser origin refused (403 forbidden on /v1/buyer/*) | the page’s origin is not registered for the bearer’s shop, the method or header is not allowed, or a sign-in/verification route was called from a partner origin | Fix the registration (Browser access and CORS). Never relay sign-in or verification through your own page. |
Wrong verification code (401 code_invalid) | the buyer typed a wrong, expired or already-used code in the consent view | Shown to the buyer by the view; they request a new code. Not an integration error. |
Verification delivery failed (502 magic_auth_send_failed / magic_auth_verify_failed) | Alyte could not send or check a code with its email provider | Retryable; the view offers a retry. Not the buyer’s answer. |
Attested consent not enabled (403 merchant_consent_not_enabled) | a merchantAttested mint on a shop Alyte staff have not enabled for it | Terminal. Mint without merchantAttested, or ask about contracted attestation. |
Attested ceiling exceeded (403 merchant_consent_ceiling_exceeded) | the grant exceeds the configured amount/duration, uses another currency, requests recurring authority, or reuses an agent with a prior permission | Use the buyer’s verification flow. Splitting the grant or revoking older grants does not reset the allowance. |
Payment provider key refused (422 psp_credentials_rejected) | an Adyen API key sent when linking or editing a payment connection was refused by Adyen before it was stored (401: invalid key; 403: no access to the merchant account) | Terminal for that key; nothing was saved. Generate a new key on the credential that owns the client key and save again. Connect Adyen |
Card setup paused (409 capture_unavailable) | the shop’s payment connection cannot be used for card setup right now: no public return URL on this deployment, or Adyen refuses the shop’s saved API key | Terminal for the buyer; not a provider hiccup, so do not retry. The shop re-enters its key or fixes its configuration. |
Card preparation unavailable (503 card_preparation_unavailable) | the provider could not verify a card during setup confirmation or preparation for a purchase | For setup, retry confirmation with the same setup reference. For a purchase, retain the same attempt and idempotency key and respect any retry delay. |
Card not authenticated (422 authentication_evidence_required) | an agent tried to charge a saved card that carried no authentication evidence when it was saved (no 3D Secure, or the provider did not report the result) | Terminal for that card. The buyer saves the card again through Alyte; on Adyen the account must report the 3D Secure result (Connect Adyen). |
Card not ready (422 card_not_chargeable) | the card has not completed the required setup | Ask the buyer to complete or repeat card setup. |
Wrong card customer (409 card_customer_mismatch) | the payment method is attached to a different provider customer | The buyer needs a card saved under the correct customer; changing the request’s buyer identity is not a fix. |
Edited out from under you (409 commerce_schedule_conflict) | a location, an event’s venue binding or a sale-window edit carried a revision that is no longer current | Reload, re-apply the change and retry. Nothing was written. Shared inventory and locations |
Inventory busy (409 inventory_busy, details.retryable: true) | deleting a tier, event or shop collided with a purchase or release touching the same stock | Retry shortly. The deletion rolled back whole; a possibly-paid ticket is never erased. |
Not enough stock to take off (409 stock_insufficient, details.availableCount) | a stock adjustment would take the tier below zero: agents hold or bought tickets you also sold | Terminal for this change; nothing changed and the requestId stays free. Reconcile: take what Alyte has under a new requestId, and send the rest when tickets come back. |
Request ID already used (409 stock_adjustment_conflict) | a stock adjustment reused a requestId for a different tier or delta | Use a new requestId. To resend the same change, send exactly the same tier and delta. |
Pool capacity reached (409 pool_capacity_exceeded, details.capacity) | a stock increase on a pooled tier would take the pool’s available and held places above its capacity | Raise the pool’s capacity with PATCH /v1/integration/pools/{id}, then send the increase again. |
Catalogue too large (413 catalog_too_large) | an inventory observation or location list would exceed 2,000 rows in one relation | No partial result is returned. Split the shop, or contact Alyte. |
Waiting for an access window (409 access_waiting, details.retryAfter) | the buyer is not yet inside an early-access window or the general sale | Nothing was charged. Retry at retryAfter with the same idempotency key. |
Over the ticket limit per customer (409 purchase_limit_exceeded, details.limit) | the purchase would take the buyer over the event’s ticket limit per customer | Terminal for this quantity; nothing was held. Tell the buyer the limit. A smaller quantity may still fit. |
Too many unpaid tickets (409 held_limit_exceeded, details.limit) | the buyer already holds as many unpaid tickets for the event as the shop allows at once | Pay for or release an existing hold, then retry. |
Purchase not tied to a buyer (409 purchase_limit_identity_required) | the event limits tickets per customer, and this purchase has no buyer Alyte can recognise, such as an organisation’s agent | Terminal for this agent. Buy through an agent the buyer created for themselves. |
Ticket limits not enabled (503 purchase_limits_unavailable) | setting a ticket limit on a deployment where the feature is not enabled | Nothing changed. Contact Alyte. |
Access settings changed (409 access_conflict) | a rule, its preview or a tier’s general-sale time changed since you read it, or the tier has scheduled windows | Refresh, review again, and send with a new request ID. Cancel windows before moving general sale. |
Access view too large (413 access_catalog_too_large / access_preview_too_large) | more than 200 rules or 100 programs in one list, or more than 2,000 queued requests in one preview | No partial result is returned. Contact Alyte. |
Access rules unavailable (503 access_unavailable / access_preview_unavailable) | the shop’s storage cannot serve access rules or a preview right now | Retry later. Nothing changed. |
Rate limited (429 rate_limited) | too many requests, sign-in links or verification codes | Retryable. Wait retryAfter seconds (also sent as the Retry-After header), then retry. A 429 without retryAfter came from a payment provider: back off. |
Card / connection mismatch (409 instrument_provider_mismatch) | a saved card is used at a shop or payment connection it was not saved for | Terminal. Cards are saved per shop and per payment connection; the buyer adds a card for this shop. |
Bank challenge unavailable (422 sca_unavailable) | the purchase needs Strong Customer Authentication that Alyte cannot run for it yet | Terminal for this purchase; not a card decline. Nothing was charged. |
Payment pending (202) | the payment provider accepted the payment but confirms it asynchronously | Not a failure and not a success yet. Do not submit the payment again. Wait for the settlement webhook or poll the payment. |
| Indeterminate payment outcomes | PSP timeout mid-charge | The charge may have succeeded. Alyte halts rather than guesses — it will never retry a possibly-succeeded charge into a double-charge, and neither should you. Re-check the payment’s status; your idempotencyKey makes a safe re-confirm possible. |
