Error codes

The resource has no customer, and an access link opens a resource only for its customer.

Fix: Set customer_id on orders before payment to link their buyers to them and to their returns.

Still stuck? Ask on Flint Help (opens in a new tab)

The merchant hosts its own customer account, so Flint has no account page for an access link to open.

Fix: Show the resource in your own account with a customer session, or set customer_account.mode to flint_hosted.

Still stuck? Ask on Flint Help (opens in a new tab)

The stored account-provisioning configuration is not supported by this application release.

Fix: Contact Flint support to repair the account setup configuration before retrying.

Still stuck? Ask on Flint Help (opens in a new tab)

The merchant is not ready for this operation.

Fix: Complete the required merchant readiness or onboarding action before retrying.

Still stuck? Ask on Flint Help (opens in a new tab)

The merchant is not ready for this operation.

Fix: Complete the required merchant readiness or onboarding action before retrying.

Still stuck? Ask on Flint Help (opens in a new tab)

The ACH debit confirmation token is missing the billing name or billing email.

Fix: Collect the buyer's billing name and email, create a new confirmation token, and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The ACH debit confirmation token does not include the buyer's online mandate acceptance.

Fix: Collect the buyer's mandate acceptance in the payment form, create a new confirmation token, and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

ACH debit cannot be offered because the order's line items do not show whether the purchase is for goods or services.

Fix: Include a physical or digital product line item, or use service products for every line item that is not a fee. Otherwise collect payment without ACH debit.

Still stuck? Ask on Flint Help (opens in a new tab)

An active bundle cannot replace its components.

Fix: Set the bundle to inactive, then replace components using the latest version.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

An active payment link cannot add, remove, or change the key or catalog source of its line items.

Fix: Keep every existing payment_link_line_item_id with its key, variant_id, and bundle_id, or set status to inactive before replacing line items.

Still stuck? Ask on Flint Help (opens in a new tab)

An optioned product must contain at least one active option.

Fix: Include at least one active option and its active values.

Still stuck? Ask on Flint Help (opens in a new tab)

The option replacement would make active variant selections indistinguishable.

Fix: Keep enough active options and values to distinguish every active variant.

Still stuck? Ask on Flint Help (opens in a new tab)

An active option cannot be added while active variants lack a selection for it.

Fix: Inactivate the variants or backfill their option selections before adding the active option.

Still stuck? Ask on Flint Help (opens in a new tab)

A failed provider refund already exists for this Affirm payment.

Fix: Do not create a new provider refund. Use an alternative reimbursement and reconcile the failed Refund.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A category name matches more than one category.

Fix: Use the intended category's handle instead of its name.

Still stuck? Ask on Flint Help (opens in a new tab)

A unit_price_overrides amount is above the line item's max_unit_price_money.

Fix: Send an amount at or below the line item's max_unit_price_money.

Still stuck? Ask on Flint Help (opens in a new tab)

The amount is below the minimum allowed for the payment option.

Fix: Send an amount at or above the payment option's minimum, or use a different payment option.

Still stuck? Ask on Flint Help (opens in a new tab)

A unit_price_overrides amount is below the line item's min_unit_price_money.

Fix: Send an amount at or above the line item's min_unit_price_money.

Still stuck? Ask on Flint Help (opens in a new tab)

The manual payment is larger than the invoice's collectible balance.

Fix: Retrieve the invoice and record an amount_money no greater than its collectible balance.

Still stuck? Ask on Flint Help (opens in a new tab)

The amount exceeds the maximum allowed for the payment option.

Fix: Send a smaller amount or use a different payment option. The error message says whether the merchant can raise the limit or must contact support.

Still stuck? Ask on Flint Help (opens in a new tab)

The refund amount is more than what remains refundable on the order or payment.

Fix: Read the order's settlement amounts and refund no more than what remains, or omit amount_money to refund exactly the remainder.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment processor's amount for this payment intent no longer matches Flint's record.

Fix: Do not retry the confirmation. Contact support with the request_id and the payment intent ID.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

unit_price_overrides names a line item whose price buyers cannot change.

Fix: Remove the line item from unit_price_overrides.

Still stuck? Ask on Flint Help (opens in a new tab)

amount_money cannot change once a payment source is attached or confirmation is attempted, or when an order owns the payment intent.

Fix: Create a new payment intent with the new amount. For a payment intent an order owns, change the order instead.

Still stuck? Ask on Flint Help (opens in a new tab)

A line item needs a buyer-entered price and unit_price_overrides has none for it.

Fix: Add the line item's key to unit_price_overrides with the price the buyer entered.

Still stuck? Ask on Flint Help (opens in a new tab)

A refund that names both line items and charges needs a top-level amount_money.

Fix: Set amount_money to the total of the named line items and charges, or send them as separate refunds.

Still stuck? Ask on Flint Help (opens in a new tab)

The amount exceeds the maximum payment amount.

Fix: Send an amount no greater than the maximum stated in the error message.

Still stuck? Ask on Flint Help (opens in a new tab)

The amount is below the minimum payment amount for the currency.

Fix: Send an amount of at least the minimum stated in the error message, in minor units.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The API key is already revoked.

Fix: Retrieve the API key to confirm its status. Revocation is permanent; create a new key if you need an active credential.

Still stuck? Ask on Flint Help (opens in a new tab)

The API key changed before the update or revocation could be applied.

Fix: Retrieve the API key, review its current state, and retry the action if it still applies.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The API key exists but is past its expiration time.

Fix: Create or use an active API key for the target mode and merchant, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The user's merchant role does not allow API key management.

Fix: Ask a merchant owner or admin to create the key, or use a credential whose role can manage API keys.

Still stuck? Ask on Flint Help (opens in a new tab)

The API key is not usable for its stored payment-mode binding.

Fix: Create or use an API key whose mode matches the target environment, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

No API key matches the provided credential.

Fix: Check the API key value or create a new API key, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request did not include an API key or accepted bearer credential.

Fix: Send a Flint API key in X-API-Key or as Authorization: Bearer <API_KEY>, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The API key exists but has been revoked.

Fix: Create or use an active API key for the target mode and merchant, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The API key is bound to a sandbox that is missing, archived, inactive, or mode-incompatible.

Fix: Create or use a sandbox-bound test key for an active sandbox, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The API key uses a legacy or unsupported scope grant.

Fix: Create a new API key with explicit public API scopes, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The API version changed before the update was committed.

Fix: Reload the resource, review its current API version, and retry with that value as expected_api_version.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested API version has retired.

Fix: Set Flint-Version to a supported version listed in the error details.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A promotion rule is missing its attribute.

Fix: Set attribute on every promotion rule and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The attribute is not available for this merchant's risk rules.

Fix: Use another attribute from the risk attribute registry. The error message explains why this one is unavailable.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be authenticated.

Fix: Send a valid Flint API key, partner install token, checkout session credential, or dashboard session for this route, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

The authenticated caller is not authorized for this operation.

Fix: Use credentials with access to the target merchant, environment, route, and scope, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The request could not be authenticated.

Fix: Send a valid Flint credential supported by this endpoint, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic promotions are turned off in the merchant's promotion settings.

Fix: Set promotions.automatic_enabled to true with PATCH /v1/settings first, or stop turning on automatic promotions in the field identified by param.

Still stuck? Ask on Flint Help (opens in a new tab)

The default line item tax category is not supported while automatic tax is connected.

Fix: Set tax.default_line_item_tax_category to general, physical_goods, prepared_food, digital_goods, software, saas, services, or professional_services.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic tax cannot calculate this taxable order charge.

Fix: Automatic tax taxes shipping and delivery charges only. Mark the charge identified by param not taxable, remove it, or use external tax.

Still stuck? Ask on Flint Help (opens in a new tab)

The tax calculation includes components in automatic mode.

Fix: Omit components, or use external mode with caller-supplied components.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic tax needs an active tax connection for the account.

Fix: Connect automatic tax in the dashboard's tax settings, use external tax, or turn tax off.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic tax requires the order payment to be captured immediately.

Fix: Pay with payment intents that use automatic capture, or use external tax.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic tax cannot apply a customer tax exemption.

Fix: Use external tax for an exempt customer, or remove the customer exemption before retrying automatic tax.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic tax cannot calculate tax-inclusive prices.

Fix: Set price_mode to additive, or use external tax for tax-inclusive prices.

Still stuck? Ask on Flint Help (opens in a new tab)

An automatic tax invoice cannot be split into installments.

Fix: Send a single full-balance schedule entry, omit schedule_entries, or use external tax.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic tax found more than one buyer destination for taxable components.

Fix: Ship, deliver, or pick up every taxable item the same way, or use external tax.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic tax found more than one seller origin.

Fix: Fulfill every taxable item from one location, split the items into separate orders, or use external tax.

Still stuck? Ask on Flint Help (opens in a new tab)

A location the order ships or is picked up from has no country or postal code.

Fix: Add a country and postal code to the location named in the message, or use external tax.

Still stuck? Ask on Flint Help (opens in a new tab)

An automatic tax invoice takes one payment for the full balance.

Fix: Record or collect the full outstanding balance in one payment, or use external tax.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic tax cannot calculate a post-tax subtotal discount.

Fix: Use subtotal_pre_tax for the discount calculation basis, or use external tax.

Still stuck? Ask on Flint Help (opens in a new tab)

Automatic tax requires the order to be paid with one payment intent.

Fix: Select a single payment intent for the full balance, or use external tax.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

Another variant or bundle already uses this barcode.

Fix: Use a barcode that no other variant or bundle uses.

Still stuck? Ask on Flint Help (opens in a new tab)

The store doesn't offer other billing intervals for this subscription.

Fix: Change it only when the subscription's billing_interval_options lists more than one option.

Still stuck? Ask on Flint Help (opens in a new tab)

An active bundle requires at least one component.

Fix: Include at least one valid component or create the bundle as inactive.

Still stuck? Ask on Flint Help (opens in a new tab)

A bundle component references a product that is not active.

Fix: Use a variant whose parent product is active, or keep the bundle inactive.

Still stuck? Ask on Flint Help (opens in a new tab)

A bundle component references a variant that is not active.

Fix: Use an active variant, or keep the bundle inactive.

Still stuck? Ask on Flint Help (opens in a new tab)

The bundle is used by an active payment link.

Fix: Deactivate every payment link that uses the bundle before changing or retiring the bundle.

Still stuck? Ask on Flint Help (opens in a new tab)

The bundle is used by an active subscription.

Fix: Cancel every active subscription that uses the bundle before changing or retiring the bundle.

Still stuck? Ask on Flint Help (opens in a new tab)

The bundle is used by an active subscription plan.

Fix: Archive every subscription plan that uses the bundle before changing or retiring the bundle.

Still stuck? Ask on Flint Help (opens in a new tab)

The bundle is used by an open checkout session.

Fix: Close every open checkout session that contains the bundle, or wait for them to close, before changing or retiring the bundle.

Still stuck? Ask on Flint Help (opens in a new tab)

The bundle is used by an open invoice payment attempt.

Fix: Cancel or wait for every open invoice payment attempt that contains the bundle before changing or retiring the bundle.

Still stuck? Ask on Flint Help (opens in a new tab)

The bundle is used by an open order.

Fix: Wait until every order that contains the bundle is no longer open before changing or retiring the bundle.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Buyer credentials cannot set merchant-owned fulfillment correlation fields.

Fix: Remove external_system and external_reference. Set merchant correlation from a server-authenticated request.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer session or invoice access token is invalid or expired.

Fix: Authenticate the buyer again or use the current token from this invoice's public URL.

Still stuck? Ask on Flint Help (opens in a new tab)

The endpoint requires a customer session or invoice access token.

Fix: Send either credential in the Authorization bearer header.

Still stuck? Ask on Flint Help (opens in a new tab)

calculation_basis was sent for a charge that uses a fixed amount.

Fix: Omit calculation_basis for amount_money charges. Send it only with percent.

Still stuck? Ask on Flint Help (opens in a new tab)

Service charge promotions do not use a calculation basis.

Fix: Omit application_method.calculation_basis when discount_class is service_charge.

Still stuck? Ask on Flint Help (opens in a new tab)

A percent charge is missing calculation_basis.

Fix: Send calculation_basis with every percent charge.

Still stuck? Ask on Flint Help (opens in a new tab)

The cancellation comment is longer than 500 characters.

Fix: Send a cancellation_comment of 500 characters or fewer.

Still stuck? Ask on Flint Help (opens in a new tab)

The store's cancellation reason list names a reason twice.

Fix: List each cancellation reason once.

Still stuck? Ask on Flint Help (opens in a new tab)

The store's cancellation reason list has more than 8 reasons.

Fix: Send at most 8 cancellation_reasons, each standard code once.

Still stuck? Ask on Flint Help (opens in a new tab)

The buyer chose a reason the store does not ask about.

Fix: Send one of the store's customer_account.buyer_capabilities.cancellation_reasons, or omit cancellation_reason_code.

Still stuck? Ask on Flint Help (opens in a new tab)

The store ends a buyer's cancellation when the billing period ends.

Fix: Omit cancel_immediately to cancel at the end of the billing period. The store can let buyers choose with customer_account.buyer_capabilities.cancellation_timing buyer_chooses.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment intent has expired and cannot be canceled.

Fix: Retrieve the payment intent to confirm its status. An expired payment intent needs no cancellation.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment intent has already succeeded and cannot be canceled.

Fix: Create a refund to return the funds instead.

Still stuck? Ask on Flint Help (opens in a new tab)

The subscription cannot be paused in its current status.

Fix: Fetch the subscription and pause it only from an active state.

Still stuck? Ask on Flint Help (opens in a new tab)

The subscription cannot be resumed in its current status.

Fix: Fetch the subscription and resume it only from a paused state.

Still stuck? Ask on Flint Help (opens in a new tab)

The subscription is still waiting for its initial payment.

Fix: Complete or recover the initial payment instead of resuming the subscription.

Still stuck? Ask on Flint Help (opens in a new tab)

The past-due subscription must recover through payment.

Fix: Update the payment method and create or await a payment retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested capabilities differ from the ones account setup already started with.

Fix: Omit requested_capabilities, or send the same capabilities as the earlier request.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

A requested capability needs another capability that the request does not include.

Fix: Add the capability named in the error message, such as receive_payouts for accept_card_payments, or omit requested_capabilities to use the default set.

Still stuck? Ask on Flint Help (opens in a new tab)

The operation needs a capability that was not requested when the merchant account was created.

Fix: Check GET /v1/capabilities, then contact Flint support to add the capability to the account.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested onboarding capability combination is not supported by Flint's current merchant-account configuration.

Fix: Request accept_card_payments and receive_payouts together. You may also include accept_ach_debit_payments, or omit requested_capabilities to use the default set.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The requested capture exceeds the authorization's current capturable amount.

Fix: Use an amount no greater than capturable_money, or omit amount_money to capture the available authorization.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment was already captured for a different amount.

Fix: Read the payment intent. Retry only with amount_money equal to the captured amount, because no further capture is possible.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested capture currency differs from the authorization currency.

Fix: Send amount_money in the capturable authorization currency.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Another category already uses this handle.

Fix: Use the existing category or choose a different handle.

Still stuck? Ask on Flint Help (opens in a new tab)

The category changed while this update was being committed.

Fix: Fetch the category and retry the intended update.

Still stuck? Ask on Flint Help (opens in a new tab)

The category is still referenced and cannot be deleted.

Fix: Remove the category from every product, bundle, promotion, and return setting, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A charge in the request does not belong to the order or has no settled amount to refund.

Fix: Use an order_charge_id from the order's charges that was collected by a succeeded payment.

Still stuck? Ask on Flint Help (opens in a new tab)

The charge refund amount is more than the charge's remaining refundable amount.

Fix: Read the order's refunds and send a charges[].amount_money no greater than what remains on that charge.

Still stuck? Ask on Flint Help (opens in a new tab)

The charges in the request add up to more than the refund amount_money.

Fix: Raise amount_money to at least the charge total, or omit it to refund exactly the named charges.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The charge has neither amount_money nor percent.

Fix: Send exactly one of charge.amount_money or charge.percent.

Still stuck? Ask on Flint Help (opens in a new tab)

Checkout authentication was rotated before payment work became durable.

Fix: Refresh the checkout session through its owning invoice or checkout entry point, then resume the same payment attempt if it remains available.

Still stuck? Ask on Flint Help (opens in a new tab)

Only the checkout session's own credential can call this route.

Fix: Send X-Checkout-Session-ID and X-Checkout-Session-Secret instead of merchant authentication.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout already acts for a customer, so it needs no code.

Fix: Save or pay with that customer's cards without a code.

Still stuck? Ask on Flint Help (opens in a new tab)

The order's customer is not the customer this checkout session was created for.

Fix: Create a new checkout session for the order.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout customer does not match the order's customer.

Fix: Omit customer_collection.customer_id or send the order's customer_id.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout names a customer, but the order has no customer.

Fix: Set customer_id on the order first, or omit customer_collection.customer_id, then create the checkout session.

Still stuck? Ask on Flint Help (opens in a new tab)

Checkout buyers cannot apply discounts by resource ID.

Fix: Provide the buyer-facing promotion code instead.

Still stuck? Ask on Flint Help (opens in a new tab)

Checkout buyers can remove only promotion-code discounts.

Fix: Remove a buyer-applied code discount or ask the merchant to change other discounts.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout launch credential is scoped to hosted checkout bootstrap and cannot authorize public API operations.

Fix: Open the hosted checkout URL so Flint can exchange the launch credential for a checkout session credential.

Still stuck? Ask on Flint Help (opens in a new tab)

Checkout buyers cannot create manual discounts.

Fix: Apply a promotion through checkout, or create the manual discount with merchant authentication.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout credential cannot update this order field.

Fix: Send only requested_tip or tax, or use a merchant credential for other order fields.

Still stuck? Ask on Flint Help (opens in a new tab)

A checkout session can list only active payment methods.

Fix: Omit status or set it to active.

Still stuck? Ask on Flint Help (opens in a new tab)

Checkout payment work is still resolving, so the competing change cannot proceed yet.

Fix: Wait for payment work on the checkout session listed in blocking_resources to finish, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The expired checkout session is in constrained recovery mode and the request targets a different payment attempt.

Fix: Read or resume only the payment attempt identified by the checkout session recovery response.

Still stuck? Ask on Flint Help (opens in a new tab)

Checkout reminder emails need a business address on the merchant, which the reminder prints.

Fix: Set address on the merchant with PATCH /v1/merchant, then turn checkout.recovery_email.enabled on again.

Still stuck? Ask on Flint Help (opens in a new tab)

The expired checkout session is in constrained recovery mode and cannot perform this operation.

Fix: Read the order or owning payment attempt, or resume that exact payment attempt before the recovery deadline.

Still stuck? Ask on Flint Help (opens in a new tab)

replace_checkout_session_id is only valid when creating an order-backed checkout session.

Fix: Send replace_checkout_session_id together with order_id, without quick_pay_item or subscription_plan_id.

Still stuck? Ask on Flint Help (opens in a new tab)

Saved payment details for checkout can only be configured for a merchant.

Fix: Send checkout.saved_payment_details in a merchant-scoped settings update.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

An open checkout session already exists for this order.

Fix: Use the checkout session listed in blocking_resources and existing_checkout_session_id, or replace it explicitly.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be authenticated.

Fix: Send a valid Flint credential supported by this endpoint, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be authenticated.

Fix: Send a valid Flint credential supported by this endpoint, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The session named by replace_checkout_session_id is no longer the order's current open session.

Fix: Refresh the session identified by current_checkout_session_id and blocking_resources before retrying the replacement.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout session line item state changed after it was read.

Fix: Use the returned line item state and latest_revision to refresh the checkout and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout session closed, so it cannot be used for this request.

Fix: Create a new checkout session for the order and continue through it.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

This checkout session cannot modify line item modifiers.

Fix: Inspect reason: existing_order_checkout uses the existing Order, invoice_finalized uses a finalized Invoice, and subscription_terms_locked uses locked subscription terms. Update the source resource when its state allows changes.

Still stuck? Ask on Flint Help (opens in a new tab)

Checkout sessions can only update line item modifiers or an unfunded gift card recipient.

Fix: Send only modifiers or gift_card_recipient, each with expected_version, or use an API key.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The authenticated caller is not authorized for this operation.

Fix: Use credentials with access to the target merchant, environment, route, and scope, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The resource is available to checkout authentication only after the checkout session is paid.

Fix: Complete payment, then retry with the same checkout session credential.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be authenticated.

Fix: Send a valid Flint credential supported by this endpoint, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The checkout credential cannot use this mode or checkout session.

Fix: Use the credential issued for this checkout session.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be authenticated.

Fix: Send a valid Flint credential supported by this endpoint, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout session request sets more than one of quick_pay_item, order_id, or subscription_plan_id.

Fix: Send exactly one of quick_pay_item, order_id, or subscription_plan_id.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout session request sets none of quick_pay_item, order_id, or subscription_plan_id.

Fix: Send exactly one of quick_pay_item, order_id, or subscription_plan_id.

Still stuck? Ask on Flint Help (opens in a new tab)

The credential cannot update this checkout session field.

Fix: Send buyer_contact and timezone with the session's checkout credential, and metadata or external_reference_id with a merchant credential.

Still stuck? Ask on Flint Help (opens in a new tab)

Hosted checkout collects an order with one payment method, and the order has more than one unpaid payment leg.

Fix: Cancel each leg in payment_intent_ids with POST /v1/orders/{order_id}/payment-intents/{payment_intent_id}/cancel, then create the session again so hosted checkout collects the balance in one payment. To take a split payment, collect it in your own payment UI, for example under an embedded checkout session.

Still stuck? Ask on Flint Help (opens in a new tab)

A payment is in progress on this checkout, so its surface can't change.

Fix: Finish or cancel the payment on existing_checkout_session_id, or request the session's current surface.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout session reached its tax calculation limit.

Fix: Start a new checkout session or contact the merchant before calculating tax again.

Still stuck? Ask on Flint Help (opens in a new tab)

Tipping is disabled for this checkout session.

Fix: Continue without a tip or start a checkout session with tipping enabled.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested tip is not available for this checkout session.

Fix: Choose one of the checkout session's configured tips or enable custom tipping.

Still stuck? Ask on Flint Help (opens in a new tab)

Codes can only be set on a promotion whose redemption_type is code.

Fix: Remove codes, or set redemption_type to code.

Still stuck? Ask on Flint Help (opens in a new tab)

A promotion whose redemption_type is code needs at least one code.

Fix: Provide at least one entry in codes, or set redemption_type to automatic.

Still stuck? Ask on Flint Help (opens in a new tab)

The promotion code is empty.

Fix: Send a code of 1 to 100 printable characters.

Still stuck? Ask on Flint Help (opens in a new tab)

The promotion code is longer than 100 characters.

Fix: Send a code of 100 characters or fewer.

Still stuck? Ask on Flint Help (opens in a new tab)

A bundle component entry is missing.

Fix: Replace the empty entry with a valid component or remove it from the array.

Still stuck? Ask on Flint Help (opens in a new tab)

The resource changed while the operation was being committed.

Fix: Fetch the current resource and retry the intended operation with its version.

Still stuck? Ask on Flint Help (opens in a new tab)

The ConfirmationToken contains a malformed payment return URL.

Fix: Create a new ConfirmationToken using the exact payment_collection.stripe.return_url.

Still stuck? Ask on Flint Help (opens in a new tab)

The ConfirmationToken return URL does not match this payment's active Flint relay.

Fix: Create a new ConfirmationToken using the exact payment_collection.stripe.return_url for this payment.

Still stuck? Ask on Flint Help (opens in a new tab)

The ConfirmationToken does not contain Flint's payment return relay URL.

Fix: Create a new ConfirmationToken using the exact payment_collection.stripe.return_url.

Still stuck? Ask on Flint Help (opens in a new tab)

The confirmation token was already used for a different payment intent.

Fix: Create a new confirmation token for this payment intent and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The confirmation token has expired.

Fix: Create a new confirmation token and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The first confirmation of this payment intent needs a confirmation token.

Fix: Send confirmation_token. Omit it only when continuing an existing payment attempt after a client action.

Still stuck? Ask on Flint Help (opens in a new tab)

The confirmation token was not found for this merchant and environment.

Fix: Create a new confirmation token for this merchant in the same environment, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The confirmation token was not created by the payment processor's browser SDK, which this payment option requires for buyer authentication.

Fix: Create the confirmation token in the browser with the payment processor's client SDK, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

An early termination fee requires a contract term.

Fix: Set contract_term_months, or remove early_termination_fee_money.

Still stuck? Ask on Flint Help (opens in a new tab)

The contract term is longer than 120 months.

Fix: Send a contract_term_months value from 1 through 120.

Still stuck? Ask on Flint Help (opens in a new tab)

The contract term is shorter than one month.

Fix: Send a contract_term_months value from 1 through 120.

Still stuck? Ask on Flint Help (opens in a new tab)

The country differs from the one account setup already started with.

Fix: Omit country, or send the same country as the earlier request.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A country is required to start live account setup.

Fix: Send country as the business's uppercase ISO 3166-1 alpha-2 code, such as US.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The credit note allocation was already reversed.

Fix: Read the allocation to confirm its reversed_at value.

Still stuck? Ask on Flint Help (opens in a new tab)

The allocation exceeds an available balance.

Fix: Use an amount no greater than both the credit note's unallocated amount and the invoice's outstanding amount.

Still stuck? Ask on Flint Help (opens in a new tab)

The correction exceeds the invoice line's remaining creditable value.

Fix: Reduce the correction amount or quantity.

Still stuck? Ask on Flint Help (opens in a new tab)

The credit note version changed.

Fix: Retrieve the credit note and retry with its current version as expected_version.

Still stuck? Ask on Flint Help (opens in a new tab)

The refund currency does not match the credit note.

Fix: Use the credit note currency.

Still stuck? Ask on Flint Help (opens in a new tab)

The credit note has active allocations.

Fix: Reverse the allocations listed in blocking_resources before voiding the credit note. A note with a pending or succeeded refund listed there cannot be voided.

Still stuck? Ask on Flint Help (opens in a new tab)

Another credit note is being issued for this merchant.

Fix: Retry with the same Idempotency-Key after the current issue finishes.

Still stuck? Ask on Flint Help (opens in a new tab)

Only draft credit notes can be changed.

Fix: Create a new draft credit note for another correction.

Still stuck? Ask on Flint Help (opens in a new tab)

The credit note has not been issued.

Fix: Issue the credit note before allocating it or downloading its PDF.

Still stuck? Ask on Flint Help (opens in a new tab)

The refund exceeds the available credit.

Fix: Use an amount no greater than the credit note unallocated_money.

Still stuck? Ask on Flint Help (opens in a new tab)

The credit note refund request is invalid.

Fix: Use a paid invoice and a caller-chosen idempotency key.

Still stuck? Ask on Flint Help (opens in a new tab)

The amount uses a different currency from the resource it applies to.

Fix: Send the amount in the currency of the invoice, order, payment, or plan it belongs to.

Still stuck? Ask on Flint Help (opens in a new tab)

The subscription plan currency is missing.

Fix: Set currency to a three-letter ISO currency code such as USD.

Still stuck? Ask on Flint Help (opens in a new tab)

The webhook stream resume values disagree.

Fix: Send either Last-Event-ID or after_event_id, or make both values identical.

Still stuck? Ask on Flint Help (opens in a new tab)

Customer account resources are temporarily unavailable.

Fix: Retry with exponential backoff.

Still stuck? Report it with your request ID (opens in a new tab)

The customer account fields do not match the selected mode.

Fix: Send merchant_account_url and route_templates only with merchant_hosted mode, and presentation only with flint_hosted mode.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer account resource was not found for this customer.

Fix: Check the resource ID. Customer-session routes never reveal another customer's resources.

Still stuck? Ask on Flint Help (opens in a new tab)

Merchant-hosted customer accounts need a merchant account URL.

Fix: Send customer_account.merchant_account_url with customer_account.mode merchant_hosted.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer still has subscriptions or saved payment methods that could remain operational after account deletion.

Fix: Cancel every non-canceled subscription and remove every saved payment method, then retry approval.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer is being deleted and cannot be changed.

Fix: Wait for the deletion to finish, or use a different active customer.

Still stuck? Ask on Flint Help (opens in a new tab)

Another customer of this merchant already uses this email address.

Fix: Use a different email address, or update the existing customer instead.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer has no email address, so there are no email preferences to read or change.

Fix: Add an email to the customer, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

customer_id cannot be cleared from a payment intent.

Fix: Send a customer ID, or omit customer_id to keep the current customer.

Still stuck? Ask on Flint Help (opens in a new tab)

customer_id can only be updated before a payment source is attached.

Fix: Omit customer_id, or create a new payment intent for the other customer.

Still stuck? Ask on Flint Help (opens in a new tab)

The saved payment method belongs to a different customer than the payment intent.

Fix: Use a payment method owned by the payment intent's customer.

Still stuck? Ask on Flint Help (opens in a new tab)

The invoice has no customer default payment term to use.

Fix: Attach a customer with a default invoice payment term, or choose another payment_due.type.

Still stuck? Ask on Flint Help (opens in a new tab)

Customer sessions are temporarily unavailable.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The customer session use window expired.

Fix: Refresh the customer session with its refresh token, then retry with the new secret.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer or customer session was not found in the selected merchant environment.

Fix: Check the resource ID and selected environment.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer session refresh token is invalid or expired.

Fix: Authenticate the buyer again and mint a new customer session.

Still stuck? Ask on Flint Help (opens in a new tab)

A rotated customer session refresh token was presented again, so the session family was revoked.

Fix: Authenticate the buyer again and mint a new customer session.

Still stuck? Ask on Flint Help (opens in a new tab)

The endpoint requires a customer session bearer credential.

Fix: Send the customer session secret in the Authorization bearer header.

Still stuck? Ask on Flint Help (opens in a new tab)

The code is wrong, has expired, was replaced by a newer code, or has no tries left, the checkout was confirmed again after the code was used, the email or number is past its limit on wrong tries, or the customer changed its email or number or was deleted after the code was sent.

Fix: Enter the code from the latest email or text, or request a new code.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer verification belongs to another customer.

Fix: Use the customer_id bound to the verification.

Still stuck? Ask on Flint Help (opens in a new tab)

A code that confirms a saved card goes to the number given with the payment, or to the customer's email, so the request names no email.

Fix: Remove email and send channel sms or email.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer verification expired.

Fix: Create a new customer verification and confirm its code.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout has requested as many codes of this channel as it can: 5 emailed codes, or 6 texted-code requests.

Fix: After a texted-code request, send the code by email instead; otherwise continue without saved details.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer verification has not been confirmed.

Fix: Confirm the Flint-sent code before linking guest purchases.

Still stuck? Ask on Flint Help (opens in a new tab)

This checkout does not offer saved payment details.

Fix: Read the checkout session and request a code only when save_payment_method_requires_verification is true.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint sent no code for a use_saved_payment_methods request with channel auto, the default: the email has no saved details at this merchant, a cap on codes was reached, or codes can't be sent right now.

Fix: Show nothing about saved details, and let the buyer pay without them.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer verification has another purpose.

Fix: Create a verification with purpose link_guest_purchases.

Still stuck? Ask on Flint Help (opens in a new tab)

Too many codes were requested for this email or from this network.

Fix: Wait, then request a new code. Codes can be requested for one email 3 times in 15 minutes and 10 times in 24 hours, and one network can make 20 requests a minute and 30 texted-code requests an hour.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint can't text a code for this checkout: the email has no details saved with a mobile phone number at this merchant, a cap on texts was reached, or texts can't be sent right now.

Fix: Offer the emailed code instead, or continue without saved details.

Still stuck? Ask on Flint Help (opens in a new tab)

Customer verification is not available right now, or a texted code couldn't be checked.

Fix: Retry in a moment, entering a texted code again, or continue without saved details.

Still stuck? Report it with your request ID (opens in a new tab)

The customer verification was already redeemed.

Fix: Retry with the same Idempotency-Key, or create and confirm a new verification.

Still stuck? Ask on Flint Help (opens in a new tab)

Checkout custom domains are available in live mode only.

Fix: Use a live-mode API key to configure a checkout custom domain.

Still stuck? Ask on Flint Help (opens in a new tab)

No custom domain of this type is set.

Fix: Set a hostname before validating it.

Still stuck? Ask on Flint Help (opens in a new tab)

The customer account hostname's payment method domain is not ready for Apple Pay and Google Pay in this environment.

Fix: Flint registers the hostname as a payment method domain when you set it. Find it with GET /v1/payment-method-domains and read validation_status and payment_options: unavailable means Flint couldn't read a wallet's status, for example while the environment's payment account isn't ready, and action_required means the registration or one of its wallets isn't active. Then set customer_account.presentation.custom_domain again, which checks the registration again; if you send an idempotency key, use a new one. Contact support with the request_id if the error persists.

Still stuck? Ask on Flint Help (opens in a new tab)

Custom domains are not active for this account.

Fix: Activate custom domains, then set the custom domain again.

Still stuck? Ask on Flint Help (opens in a new tab)

The custom domain is in use by another account, as the other custom hostname, or in another environment.

Fix: Use a different hostname, or remove it where it is set and then set it again. If another account used it, verify ownership after that account removes it.

Still stuck? Ask on Flint Help (opens in a new tab)

This custom domain was checked less than a minute ago.

Fix: Wait for Retry-After, then validate the custom domain again.

Still stuck? Ask on Flint Help (opens in a new tab)

A custom field has no key.

Fix: Set custom_fields[].key to a non-empty value that is unique within the payment link.

Still stuck? Ask on Flint Help (opens in a new tab)

A custom field key is longer than 243 characters.

Fix: Shorten custom_fields[].key to 243 characters or fewer.

Still stuck? Ask on Flint Help (opens in a new tab)

A custom field key has leading or trailing whitespace.

Fix: Remove the leading and trailing whitespace from custom_fields[].key.

Still stuck? Ask on Flint Help (opens in a new tab)

A custom field has no label.

Fix: Set custom_fields[].label to the text the buyer sees.

Still stuck? Ask on Flint Help (opens in a new tab)

A dropdown custom field option is longer than 4,096 characters.

Fix: Shorten each custom_fields[].options entry to 4,096 characters or fewer.

Still stuck? Ask on Flint Help (opens in a new tab)

A dropdown custom field option has leading or trailing whitespace.

Fix: Remove the leading and trailing whitespace from each custom_fields[].options entry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request exceeded a Flint rate or usage limit.

Fix: Retry with exponential backoff and jitter. Use the Retry-After header when present.

Still stuck? Ask on Flint Help (opens in a new tab)

A public resource referenced another resource that could not be resolved during expansion.

Fix: Contact support with the request_id; this indicates a Flint data-integrity defect.

Still stuck? Report it with your request ID (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The calculation behind the delivery selection expired before payment began.

Fix: Create a new delivery quote, select a current option, and retry payment.

Still stuck? Ask on Flint Help (opens in a new tab)

This checkout requires a rate supplied by the merchant server.

Fix: Create the delivery quote from the merchant server and then let the buyer select from the resulting options.

Still stuck? Ask on Flint Help (opens in a new tab)

The selected delivery obligations require incompatible commerce treatment.

Fix: Change the delivery method or obligation configuration so the selected quantities share compatible tax, currency, and destination treatment.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery configuration does not satisfy its typed contract.

Fix: Fix the field identified by the response and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A pinned delivery dependency was revoked and can no longer authorize a new quote or selection.

Fix: Publish or select a replacement configuration revision, then create a new quote.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery address is incomplete.

Fix: Provide line1, city, and country, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The order requires a complete delivery address.

Fix: Provide delivery_destination.address and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The current delivery selection controls the order's delivery destination.

Fix: Change or clear the delivery selection instead of updating delivery_destination directly.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery address country is invalid.

Fix: Use a two-letter ISO 3166-1 country code and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A delivery destination field exceeds its maximum length.

Fix: Shorten the field identified by param and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The order's delivery destination can no longer be changed.

Fix: Read the current order and use fulfillment recipient corrections for execution changes.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery destination is invalid.

Fix: Fix the destination field identified by the response and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

This order has no shipment or local delivery that can use a delivery destination.

Fix: Remove delivery_destination or add a line item with a shipment or local-delivery obligation.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery destination update is ambiguous.

Fix: Send delivery_destination as an object to replace it or null to clear it.

Still stuck? Ask on Flint Help (opens in a new tab)

The checkout delivery eligibility context changed after the request basis was read.

Fix: Read the current eligibility revision and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The current delivery selection basis is required.

Fix: Send the current delivery selection ID, or null when no selection exists.

Still stuck? Ask on Flint Help (opens in a new tab)

The expected_version write fence is not a positive integer.

Fix: Read the current resource, then retry with its version as expected_version.

Still stuck? Ask on Flint Help (opens in a new tab)

This delivery change requires an explicit expected_version write fence.

Fix: Read the current resource, then retry with its version as expected_version.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery external reference is already bound to another selection.

Fix: Reuse the existing selection or submit a new external reference.

Still stuck? Ask on Flint Help (opens in a new tab)

The request includes a field that does not apply to this delivery resource.

Fix: Remove the field identified by param and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request omits a field required by this delivery resource.

Fix: Provide the field identified by param and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery obligations cannot form a valid set of buyer choices.

Fix: Change the assigned delivery profiles, origin policies, or splitting rules before creating another quote.

Still stuck? Ask on Flint Help (opens in a new tab)

This delivery input requires merchant authentication.

Fix: Create the quote from the merchant server with an API key.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment link has no line item that can use a delivery method.

Fix: Clear delivery_method_ids, or use a catalog-backed line item with an applicable delivery profile.

Still stuck? Ask on Flint Help (opens in a new tab)

Delivery method assignment is temporarily unavailable.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The selected delivery option belongs to another selection.

Fix: Read the current selection, then retry with its ID as the compare-and-swap value.

Still stuck? Ask on Flint Help (opens in a new tab)

The selected delivery option or its guarantee expired.

Fix: Create a new delivery quote and select a current option.

Still stuck? Ask on Flint Help (opens in a new tab)

The selected option does not belong to the specified choice group.

Fix: Use an option ID from the same choice group in the quote response.

Still stuck? Ask on Flint Help (opens in a new tab)

The current delivery selection changed during the pickup search.

Fix: Read the current delivery selection and retry with its ID.

Still stuck? Ask on Flint Help (opens in a new tab)

The pickup availability input is invalid.

Fix: Fix the field identified by the response and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not evaluate the pickup locations.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The requested pickup location is not available for the configured delivery methods.

Fix: Choose a pickup location from the configured collection and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery preview input is invalid.

Fix: Fix the field identified by the response and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested methods cannot fulfill at least one line item's allowed fulfillment types.

Fix: Change delivery_method_ids or line_items[].fulfillment.allowed_types so at least one requested method supports each line item.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested preview depends on checkout-only state.

Fix: Create or update a checkout session, then request a checkout delivery quote.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not construct trustworthy cart, routing, or dependency lineage for the preview.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The selected delivery profile does not apply to the component product type.

Fix: Use a delivery profile that supports the referenced product type.

Still stuck? Ask on Flint Help (opens in a new tab)

The pending quote no longer matches the supplied checkout inputs.

Fix: Create a new quote from the current checkout inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery quote or one of its options expired.

Fix: Create a new delivery quote and select a current option.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery quote still requires caller input or rates.

Fix: Supply every input or caller-supplied method result requested by the pending quote.

Still stuck? Ask on Flint Help (opens in a new tab)

The selected destination conflicts with address facts used by the quote.

Fix: Create a new delivery quote using the selected destination.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery quote input is invalid.

Fix: Fix the field identified by the response and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery quote was revoked.

Fix: Create a new quote.

Still stuck? Ask on Flint Help (opens in a new tab)

The quote no longer matches the current checkout authority.

Fix: Create a new delivery quote and retry the selection.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not calculate a delivery quote.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The delivery selection is missing recipient details that the selected delivery requires.

Fix: Create a delivery selection that includes every field in missing_or_invalid_fields, with the current selection's ID as expected_delivery_selection_id, then retry payment.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery request does not satisfy the endpoint contract.

Fix: Fix the field identified by the response and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Current references depend on this delivery resource.

Fix: Remove the blocking references before retrying. For delivery methods, remove the method from settings.checkout.default_delivery_method_ids with PATCH /v1/settings, and remove it from the referencing payment links' delivery_method_ids with PATCH /v1/payment-links/{payment_link_id}.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery resource does not exist in the authenticated merchant environment.

Fix: Check the resource ID and environment, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery resource changed before the requested update was committed.

Fix: Read the current resource version, reapply the intended change, and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The current delivery selection changed after the request basis was read.

Fix: Read the effective selection, create a replacement-basis quote, and retry with its exact selection ID.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery selection expired before payment began.

Fix: Create a new delivery quote, select a current option, and retry payment.

Still stuck? Ask on Flint Help (opens in a new tab)

The selection does not choose one option for every choice group.

Fix: Submit exactly one choice for every choice group in the quote.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery selection can no longer be changed after payment begins.

Fix: Read the current order and continue with its committed delivery selection.

Still stuck? Ask on Flint Help (opens in a new tab)

This checkout reached its protected delivery selection history limit.

Fix: Finish or restart the checkout. Terminal private payloads become eligible for redaction after their retention period.

Still stuck? Ask on Flint Help (opens in a new tab)

Delivery selection is temporarily unavailable.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

Delivery configuration is temporarily unavailable.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The delivery resource is not in a state that allows the operation.

Fix: Read the current resource and choose an operation valid for its lifecycle state.

Still stuck? Ask on Flint Help (opens in a new tab)

A delivery status change must be requested separately from other mutable fields.

Fix: Send status and expected_version in their own PATCH request.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested delivery resource status is invalid.

Fix: Use active or inactive when creating a delivery method.

Still stuck? Ask on Flint Help (opens in a new tab)

The store does not allow buyers to change subscription delivery.

Fix: Ask the store to update the preference or enable customer_account.buyer_capabilities.can_update_delivery.

Still stuck? Ask on Flint Help (opens in a new tab)

The selected delivery window expired.

Fix: Create a new delivery quote and select a current window.

Still stuck? Ask on Flint Help (opens in a new tab)

The selected window was not offered by the chosen delivery option.

Fix: Use a delivery_window_id from the selected option, or omit it when the option does not require a window.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The demo session key cannot access this route.

Fix: Use a merchant API key for this route, or call a route supported by demo sessions.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The description is too long.

Fix: Use no more than 2,048 characters for a product, bundle, or subscription plan description, or 500 characters for a promotion description.

Still stuck? Ask on Flint Help (opens in a new tab)

The device has been deleted.

Fix: Use the ID of an active device.

Still stuck? Ask on Flint Help (opens in a new tab)

The device does not belong to the given location.

Fix: Send a device_id assigned to location_id, or change location_id to the device's location.

Still stuck? Ask on Flint Help (opens in a new tab)

The promotion needs discounted_item_rules to identify what it discounts.

Fix: Add application_method.discounted_item_rules. A line_item promotion can omit them only when its eligibility_rules use line_item conditions alone.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request did not include any order discount IDs.

Fix: Send at least one ID in order_discount_ids.

Still stuck? Ask on Flint Help (opens in a new tab)

One or more order_discount_ids do not match a discount on this order, or an ID is repeated.

Fix: Read the order and send each of its discount IDs at most once.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The promotion display_name is longer than 255 characters.

Fix: Send a display_name of 255 characters or fewer.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A donation payment link needs the buyer's donation amount.

Fix: Send the amount in unit_price_overrides under the key donation.

Still stuck? Ask on Flint Help (opens in a new tab)

Donation amount settings apply only to donation payment links.

Fix: Remove donation_suggested_amount_money_options, donation_min_amount_money, and donation_max_amount_money, or create the link with payment_link_type set to donation.

Still stuck? Ask on Flint Help (opens in a new tab)

A donation payment link cannot include line_items.

Fix: Remove line_items. Flint creates the donation line item for a donation payment link.

Still stuck? Ask on Flint Help (opens in a new tab)

The donation payment link has no line item with an adjustable price to hold the donation amount settings.

Fix: Replace line_items with a line item that sets allow_unit_price_adjustment to true, then update the donation amounts.

Still stuck? Ask on Flint Help (opens in a new tab)

A donation payment link cannot use a subscription plan.

Fix: Remove subscription_plan_id, or use a payment_link_type other than donation.

Still stuck? Ask on Flint Help (opens in a new tab)

Promotions cannot be enabled on a donation payment link.

Fix: Set promotion_config.automatic_enabled and promotion_config.codes_enabled to false, or omit them.

Still stuck? Ask on Flint Help (opens in a new tab)

Tax cannot be enabled on a donation payment link.

Fix: Set tax.enabled to false or omit it.

Still stuck? Ask on Flint Help (opens in a new tab)

Tips cannot be configured on a donation payment link.

Fix: Omit tip, or set only tip.enabled to false.

Still stuck? Ask on Flint Help (opens in a new tab)

A dropdown custom field has no options.

Fix: Provide at least one entry in custom_fields[].options for each dropdown field.

Still stuck? Ask on Flint Help (opens in a new tab)

A bundle component ID appears more than once in the replacement.

Fix: Include each bundle_component_id only once.

Still stuck? Ask on Flint Help (opens in a new tab)

requested_capabilities lists the same capability more than once.

Fix: Send each capability once.

Still stuck? Ask on Flint Help (opens in a new tab)

The request names the same order charge more than once.

Fix: Send each order_charge_id once in charges.

Still stuck? Ask on Flint Help (opens in a new tab)

A client option key appears more than once in the create request.

Fix: Use a unique client_option_key for each option.

Still stuck? Ask on Flint Help (opens in a new tab)

A client value key appears more than once within an option.

Fix: Use a unique client_value_key for each value in the option.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A variant appears more than once in the bundle components.

Fix: Include each variant_id only once and express the desired count with quantity.

Still stuck? Ask on Flint Help (opens in a new tab)

Two custom fields use the same key.

Fix: Give each custom field a unique key.

Still stuck? Ask on Flint Help (opens in a new tab)

line_items lists the same order line item more than once.

Fix: Send each order_line_item_id once, with its total quantity.

Still stuck? Ask on Flint Help (opens in a new tab)

Two images in the gallery use the same external reference ID.

Fix: Use a unique external_reference_id for each image in the gallery.

Still stuck? Ask on Flint Help (opens in a new tab)

The same source URL appears more than once in the gallery.

Fix: Include each source_url only once in the gallery.

Still stuck? Ask on Flint Help (opens in a new tab)

An invoice line appears more than once in the credit note.

Fix: Combine the correction into one credit note line per invoice line.

Still stuck? Ask on Flint Help (opens in a new tab)

Two invoice payment option limits use the same payment option and currency.

Fix: Send one limit per payment option and currency in invoices.payment_policy.payment_option_limits.

Still stuck? Ask on Flint Help (opens in a new tab)

Two invoice reminder rules use the same days_from_due.

Fix: Send each days_from_due value once in invoices.reminder_policy.rules.

Still stuck? Ask on Flint Help (opens in a new tab)

A subscription plan line item ID appears more than once in line_items.

Fix: Include each subscription_plan_line_item_id only once.

Still stuck? Ask on Flint Help (opens in a new tab)

Two line items use the same key.

Fix: Give each line item a unique key, or omit key to have Flint generate one.

Still stuck? Ask on Flint Help (opens in a new tab)

The request names the same order line item more than once.

Fix: Send each order_line_item_id once in line_items. Combine its quantity or amount into one entry.

Still stuck? Ask on Flint Help (opens in a new tab)

An option ID appears more than once in the replacement.

Fix: Include each option_id only once.

Still stuck? Ask on Flint Help (opens in a new tab)

Two product options use the same name.

Fix: Use a unique name for each product option.

Still stuck? Ask on Flint Help (opens in a new tab)

A variant selects more than one value for the same option.

Fix: Select exactly one value for each option.

Still stuck? Ask on Flint Help (opens in a new tab)

An option value ID appears more than once in the replacement.

Fix: Include each option_value_id only once within its option.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Two replacement custom fields use the same payment_link_custom_field_id.

Fix: Include each payment_link_custom_field_id at most once, or omit it to create a new custom field.

Still stuck? Ask on Flint Help (opens in a new tab)

Two replacement line items use the same payment_link_line_item_id.

Fix: Include each payment_link_line_item_id at most once, or omit it to create a new line item.

Still stuck? Ask on Flint Help (opens in a new tab)

A payment option and currency pair has more than one limit.

Fix: Send at most one limit for each payment option and currency.

Still stuck? Ask on Flint Help (opens in a new tab)

The request includes the same scope more than once.

Fix: Remove the duplicate scope and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request includes the same tax breakdown more than once.

Fix: Provide each tax_breakdown_id once.

Still stuck? Ask on Flint Help (opens in a new tab)

The tax calculation contains duplicate components.

Fix: Send one component for each jurisdiction code, tax_type, and calculation_type combination.

Still stuck? Ask on Flint Help (opens in a new tab)

Two values in one product option use the same label.

Fix: Use a unique value label within each option.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The email change confirmation window expired.

Fix: Request a new email change confirmation.

Still stuck? Ask on Flint Help (opens in a new tab)

The email change confirmation code is invalid.

Fix: Enter the latest code sent to the new address.

Still stuck? Ask on Flint Help (opens in a new tab)

The email change confirmation could not be delivered.

Fix: Retry the request. The current customer email remains unchanged.

Still stuck? Report it with your request ID (opens in a new tab)

The customer requested too many email changes within 15 minutes.

Fix: Wait 15 minutes, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The email preference link is invalid or belongs to another merchant environment.

Fix: Use the token from the buyer's latest email with the merchant key for that environment.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Embedded checkout needs a clean merchant return destination for redirect payment options.

Fix: Set redirects.success_redirect_url to the HTTPS storefront URL that should recover this checkout.

Still stuck? Ask on Flint Help (opens in a new tab)

requested_capabilities is an empty array.

Fix: Send at least one capability, or omit requested_capabilities to use the default set.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The authenticated caller is not authorized for this operation.

Fix: Use credentials with access to the target merchant, environment, route, and scope, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

event_config applies only to event payment links.

Fix: Remove event_config, or use a payment link whose payment_link_type is event.

Still stuck? Ask on Flint Help (opens in a new tab)

An event payment link needs at least one line item for its ticket tiers.

Fix: Add at least one line item to line_items.

Still stuck? Ask on Flint Help (opens in a new tab)

An event payment link cannot use a subscription plan.

Fix: Remove subscription_plan_id and describe ticket tiers in line_items.

Still stuck? Ask on Flint Help (opens in a new tab)

The event does not have enough tickets left for this order.

Fix: Request fewer tickets if some remain, or stop selling the event.

Still stuck? Ask on Flint Help (opens in a new tab)

No tickets were selected for the event payment link.

Fix: Set quantity_overrides to 1 or more for at least one ticket tier.

Still stuck? Ask on Flint Help (opens in a new tab)

An event date was set without an event timezone.

Fix: Send event_config.timezone with an IANA timezone name such as America/New_York along with event_config.event_at.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A service required for an accepted expansion is unavailable.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The requested expansion exceeded a route fanout or response-size limit.

Fix: Request fewer expansions or use follow-up read/list endpoints.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not resolve an accepted expansion.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

A checkout session payment was started without expected_outstanding_money.

Fix: Send the balance the buyer approved as expected_outstanding_money. If you send the corrected request, use a new idempotency key.

Still stuck? Ask on Flint Help (opens in a new tab)

This change requires an explicit expected_version write fence.

Fix: Read the current resource, then retry with its version as expected_version.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

The explicit tax_money equals the tax the line would refund automatically.

Fix: Use tax_refund_mode automatic to refund the full tax, or send a smaller tax_money to withhold part of it.

Still stuck? Ask on Flint Help (opens in a new tab)

The authenticated caller is not authorized for this operation.

Fix: Use credentials with access to the target merchant, environment, route, and scope, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A transaction image referenced an external URL instead of a Flint-owned canonical image.

Fix: Ingest the image on an image-bearing resource, then use the untransformed image.url returned by Flint.

Still stuck? Ask on Flint Help (opens in a new tab)

The billing account reached its monthly limit for externally recorded paid orders.

Fix: Request a higher allowance from Flint, or record the payment after the monthly limit resets.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment processor could not complete a required customer or payment method operation.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

An external tax calculation has no components.

Fix: Provide at least one component for each taxable line item or charge.

Still stuck? Ask on Flint Help (opens in a new tab)

Feedback reports are temporarily unavailable.

Fix: Retry with exponential backoff and the same idempotency key when creating a report.

Still stuck? Report it with your request ID (opens in a new tab)

The feedback report was not found in this merchant environment.

Fix: Check the feedback report ID and use a credential for the environment that created it.

Still stuck? Ask on Flint Help (opens in a new tab)

The authenticated caller is not allowed to set this field or value.

Fix: Remove the field or use a caller authorized for that operation, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

This field cannot be set for this operation.

Fix: Remove the field identified by the response and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A required request field is missing.

Fix: Supply the field named by param and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The flat tax is not fully attributable to refundable payment settlements.

Fix: Read the order payment state and retry after every payment settlement is available.

Still stuck? Ask on Flint Help (opens in a new tab)

A flat tax component uses an unsupported price mode.

Fix: Set price_mode to additive for a flat_amount component.

Still stuck? Ask on Flint Help (opens in a new tab)

A flat tax must be refunded for its full remaining amount or omitted.

Fix: Set tax_money to the full remaining flat tax amount, or omit this tax breakdown.

Still stuck? Ask on Flint Help (opens in a new tab)

Stored flat-tax refund lineage is inconsistent with whole-or-nothing reversal.

Fix: Contact support with the request_id so Flint can repair the refund lineage.

Still stuck? Ask on Flint Help (opens in a new tab)

A flat tax component was assigned to a line item or charge.

Fix: Move flat tax components to the order-level tax calculation, or use a percentage component for the line item or charge.

Still stuck? Ask on Flint Help (opens in a new tab)

The card is unavailable at this store or its store consent was revoked.

Fix: List /v1/me/flint-wallet/payment-methods and select a current card handle for this store.

Still stuck? Ask on Flint Help (opens in a new tab)

Cards saved with Flint are unavailable for this store account session.

Fix: Sign in with an emailed code at a Flint-hosted store account. Merchant-created sessions, checkout sessions, email links, grants, and API keys cannot open the wallet.

Still stuck? Ask on Flint Help (opens in a new tab)

Cards saved with Flint are temporarily unavailable.

Fix: Retry with exponential backoff, or pay with another payment method.

Still stuck? Report it with your request ID (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The fulfillment cannot take the requested action now, because of its current status or because its payment has an active fulfillment hold.

Fix: Retrieve the fulfillment and choose an action from its supported_actions. When the error includes current_resource, its supported_actions list is current.

Still stuck? Ask on Flint Help (opens in a new tab)

A shipment fulfillment cannot release its quantity while it has a shipment that is not voided.

Fix: Void the fulfillment's shipments first, or fail it with release_quantity set to false.

Still stuck? Ask on Flint Help (opens in a new tab)

This fulfillment requires explicit merchant approval before work begins.

Fix: Accept the fulfillment, then advance it into preparation, movement, or completion.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The fulfillment changed after the submitted version was read.

Fix: Read the current fulfillment and retry with its version as expected_version.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Completion timestamps can be recorded only on a completed fulfillment.

Fix: Complete the fulfillment with the complete action, then correct its completion timestamp with PATCH if needed.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The fulfillment details object does not match the fulfillment type.

Fix: Send the details object for the fulfillment's type, such as pickup_details for a pickup fulfillment.

Still stuck? Ask on Flint Help (opens in a new tab)

An event with this external_system and external_event_id already exists with different details.

Fix: Resend the original event unchanged, or use a new external_event_id for a different event.

Still stuck? Ask on Flint Help (opens in a new tab)

occurred_before must not be earlier than occurred_after.

Fix: Correct the occurrence-time range and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

external_system and external_event_id must be sent together.

Fix: Send both external_system and external_event_id, or omit both.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A fulfillment text field is longer than its limit.

Fix: Shorten the field named by param to the length stated in the error message.

Still stuck? Ask on Flint Help (opens in a new tab)

The fulfillment is canceled, failed, or marked no-show, so it cannot take this change.

Fix: Use an active fulfillment, or create a new fulfillment for the items.

Still stuck? Ask on Flint Help (opens in a new tab)

label_url points outside Flint, but external_system is missing.

Fix: Send external_system with an external label_url, or use a Flint-hosted label URL.

Still stuck? Ask on Flint Help (opens in a new tab)

label_url is not an absolute HTTPS URL without credentials.

Fix: Send an absolute https URL with no user name or password.

Still stuck? Ask on Flint Help (opens in a new tab)

The fulfillment has no line items.

Fix: Send at least one entry in line_items.

Still stuck? Ask on Flint Help (opens in a new tab)

A fulfillment line item is missing order_line_item_id.

Fix: Send order_line_item_id for every entry in line_items.

Still stuck? Ask on Flint Help (opens in a new tab)

The assigned delivery methods cannot fulfill every item that requires delivery.

Fix: Assign, for each item, a method whose type is in the item's delivery profile allowed_types: in delivery_method_ids on the checkout session or payment link, or in settings.checkout.default_delivery_method_ids, which payment links without methods and invoice checkouts use.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery method IDs include the same ID more than once.

Fix: Include each delivery method ID only once.

Still stuck? Ask on Flint Help (opens in a new tab)

The request assigns more than 25 delivery methods.

Fix: Assign at most 25 delivery method IDs.

Still stuck? Ask on Flint Help (opens in a new tab)

A delivery method assigned to a checkout, payment link, or checkout default, or a zone, location set, or rate callback it uses, is missing or not active.

Fix: Use IDs of active delivery methods whose zones, location sets, and rate callbacks are active. When present, blocking_resources names the resource to replace or activate.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not prepare the buyer notification for this fulfillment change.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The order line item has no fulfillment requirement that this fulfillment can cover.

Fix: Include only line items whose fulfillment requirement is required with resolution_mode manual or quote.

Still stuck? Ask on Flint Help (opens in a new tab)

The bundle component needs a delivery profile.

Fix: Set delivery_profile_id to an applicable active profile.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The delivery profile is not available.

Fix: Use an active delivery profile in the same environment, or omit delivery_profile_id when the catalog default applies.

Still stuck? Ask on Flint Help (opens in a new tab)

A failed fulfillment must say whether to release its quantity.

Fix: Set release_quantity to true to release the items or false to preserve them, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A fulfillment line item quantity is more than the quantity left to fulfill.

Fix: Send a quantity no greater than the line item's unfulfilled quantity.

Still stuck? Ask on Flint Help (opens in a new tab)

The line item quantity would be less than the quantity in its active fulfillments.

Fix: Keep quantity at or above the quantity in active fulfillments, or cancel those fulfillments first.

Still stuck? Ask on Flint Help (opens in a new tab)

A fulfillment line item quantity is zero or negative.

Fix: Send a quantity greater than zero for each entry in line_items.

Still stuck? Ask on Flint Help (opens in a new tab)

The fulfillment transition reason is not valid for this action.

Fix: Use one of the reason values documented for the action and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

An ad-hoc line item is missing its explicit fulfillment requirement.

Fix: Provide the line item's fulfillment object and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

scheduled_start_at is not earlier than scheduled_end_at.

Fix: Send a scheduled_start_at that is earlier than scheduled_end_at.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

This checkout requires a delivery selection before payment can begin.

Fix: Create a current delivery quote, select one option for every choice group, then retry payment.

Still stuck? Ask on Flint Help (opens in a new tab)

The shipment is past the packed stage, so its packages and contents cannot change.

Fix: Change packages only while the shipment is created or packed.

Still stuck? Ask on Flint Help (opens in a new tab)

The shipment is past the packed stage and cannot be voided.

Fix: Void a shipment only while it is created or packed.

Still stuck? Ask on Flint Help (opens in a new tab)

Another shipment already uses this external_system and external_reference_id.

Fix: Send a unique external_reference_id, or repeat the original create request unchanged to get the existing shipment.

Still stuck? Ask on Flint Help (opens in a new tab)

external_reference_id was sent without external_system.

Fix: Send external_system together with external_reference_id.

Still stuck? Ask on Flint Help (opens in a new tab)

The shipment is delivered or voided, so only metadata can change.

Fix: Send only metadata for this shipment and its packages.

Still stuck? Ask on Flint Help (opens in a new tab)

The fulfillment, shipment, or package changed while this request was being saved.

Fix: Read the current resource and retry the change.

Still stuck? Ask on Flint Help (opens in a new tab)

The fulfillment transition reason_message exceeds the supported length.

Fix: Use reason_message no longer than 500 characters.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A window, schedule, or expiry time was sent without the details timezone.

Fix: Send timezone in the same details object, using an IANA name such as America/New_York.

Still stuck? Ask on Flint Help (opens in a new tab)

tracking_url is not an absolute HTTPS URL without credentials.

Fix: Send an absolute https URL with no user name or password.

Still stuck? Ask on Flint Help (opens in a new tab)

A line item's delivery profile does not allow this fulfillment type.

Fix: Use a type allowed for every included line item, or create a separate fulfillment for each type.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

window_start_at is not earlier than window_end_at.

Fix: Send a window_start_at that is earlier than window_end_at.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card operation's outcome could not be confirmed.

Fix: Retry with the same Idempotency-Key to recover the original operation; do not submit a new key for an uncertain outcome.

Still stuck? Report it with your request ID (opens in a new tab)

The gift card authorization or allocation changed before payment.

Fix: Refresh the order, apply the current code when required, and accept the new allocation before payment.

Still stuck? Ask on Flint Help (opens in a new tab)

The order has selected gift cards but the payment does not accept their allocation.

Fix: Read the order and send its current gift_card_estimate amounts and order_revision in accepted_gift_card_allocation.

Still stuck? Ask on Flint Help (opens in a new tab)

A bundle cannot contain a gift card variant.

Fix: Sell the gift card as a separate line item.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card purchase requires a valid device identifier.

Fix: Send a stable 32-character lowercase hexadecimal identifier in Flint-Buyer-Device.

Still stuck? Ask on Flint Help (opens in a new tab)

Gift card purchases require an identified buyer.

Fix: Set customer_id on the order or verify the buyer in checkout before paying.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card variant has incompatible tax, inventory, or currency settings.

Fix: Use USD, set taxable to false, and remove tax_category and inventory_item_id.

Still stuck? Ask on Flint Help (opens in a new tab)

A gift card challenge is required after repeated failed codes.

Fix: Show the challenge from remediation.next_actions to the buyer, then retry the same request with its proof in Flint-Gift-Card-Challenge. If there is no next action, launch the checkout session with page_origin.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card face value, price mode, or custom amount bounds are invalid.

Fix: Use positive USD values up to 200000 cents, bounds that contain the reference face value, and face_value or discounted price mode. Discounted pricing must collect less than the face value.

Still stuck? Ask on Flint Help (opens in a new tab)

The variant's product is not a gift card.

Fix: Omit gift_card_configuration or create a product with product_type gift_card.

Still stuck? Ask on Flint Help (opens in a new tab)

Gift card variants require USD.

Fix: Use USD for unit_price_money.currency.

Still stuck? Ask on Flint Help (opens in a new tab)

Gift card value can only pay for orders in USD.

Fix: Use an order in USD.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card has insufficient available value for the requested allocation.

Fix: Refresh the balance and accept a new allocation before payment.

Still stuck? Ask on Flint Help (opens in a new tab)

Gift card variants cannot track inventory.

Fix: Omit inventory_item_id and inventory_item.

Still stuck? Ask on Flint Help (opens in a new tab)

Gift card variants cannot include modifiers.

Fix: Omit modifier_set_id.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card resource or code is not valid in this merchant environment.

Fix: Check the resource identity or full code and the credential's merchant and environment.

Still stuck? Ask on Flint Help (opens in a new tab)

A gift_card product_type cannot change to or from another type.

Fix: Create a separate product with the required product_type.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card purchase cannot be funded under its original terms or funding limits.

Fix: Keep the original buyer and offer, resolve any existing payment attempt, and check the buyer funding limit before starting another payment.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card purchase amount or recipient is invalid.

Fix: Choose a USD face value within the variant's denomination or custom amount bounds. Use a valid recipient email, a message of at most 200 characters, and a send_at between now and 90 days from now.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card purchase exceeds a daily purchase limit.

Fix: Wait until the next UTC day before starting a new purchase attempt.

Still stuck? Ask on Flint Help (opens in a new tab)

This line item does not sell a gift card.

Fix: Use gift_card_purchase only with a gift_card variant.

Still stuck? Ask on Flint Help (opens in a new tab)

The original gift card purchase value is unavailable for this cash refund.

Fix: Check the original funding load and pending refunds. Refund only eligible unspent value and resolve any reserved or spent value before retrying.

Still stuck? Ask on Flint Help (opens in a new tab)

A gift card purchase requires a catalog variant.

Fix: Supply the variant_id of a gift_card product. Ad-hoc gift card purchase lines are not supported.

Still stuck? Ask on Flint Help (opens in a new tab)

Gift card purchase identity or velocity verification is unavailable.

Fix: Retry the original request with the same Idempotency-Key after verification becomes available.

Still stuck? Report it with your request ID (opens in a new tab)

Fresh identity verification is required for gift card recipient, secret replacement, or delegation access.

Fix: Verify your identity again, then retry the original request with the same Idempotency-Key.

Still stuck? Ask on Flint Help (opens in a new tab)

The original gift card cannot accept the full refund within its lifecycle and balance cap.

Fix: Select replacement for that gift card allocation and retry with a new Idempotency-Key.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card operation conflicts with a balance, lifecycle or version constraint.

Fix: Retrieve the current resource and resolve its stated constraint before submitting a new operation.

Still stuck? Ask on Flint Help (opens in a new tab)

Gift card variants cannot be sold through subscriptions.

Fix: Use a one-time purchase.

Still stuck? Ask on Flint Help (opens in a new tab)

Gift card value cannot pay for subscription orders.

Fix: Remove selected gift cards and use a processor payment source.

Still stuck? Ask on Flint Help (opens in a new tab)

Gift card variants cannot include tax.

Fix: Set taxable to false and omit line_item_tax_category.

Still stuck? Ask on Flint Help (opens in a new tab)

The gift card code is not available for this order.

Fix: Check the current code and the issuing merchant.

Still stuck? Ask on Flint Help (opens in a new tab)

A delivery method with caller_supplied pricing cannot be used by hosted checkout or a payment link.

Fix: Use delivery methods with another pricing type in delivery_method_ids or settings.checkout.default_delivery_method_ids, or create an embedded checkout session.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

A request with the same idempotency key is still in progress.

Fix: Wait briefly and retry with the same idempotency key.

Still stuck? Ask on Flint Help (opens in a new tab)

This operation requires an idempotency key.

Fix: Send a unique Idempotency-Key header and reuse it for retries of the same logical operation.

Still stuck? Ask on Flint Help (opens in a new tab)

The idempotency key was reused with a different request body.

Fix: Use the original request body with this idempotency key, or generate a new idempotency key for a new operation.

Still stuck? Ask on Flint Help (opens in a new tab)

The idempotency key exceeds the supported length.

Fix: Send an Idempotency-Key header no longer than 255 characters.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The payment-link resolution with this context and idempotency key is still in progress.

Fix: Wait briefly and retry with the same resolution_context and Idempotency-Key.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint could not complete the request because a required service or internal operation failed.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

Flint could not reach its identity service.

Fix: Retry the request after a short delay.

Still stuck? Report it with your request ID (opens in a new tab)

The image source is animated, but Flint accepts still images only.

Fix: Provide a still JPEG, PNG, or WebP image, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The canonical image has expired or was deleted.

Fix: Re-supply the original source_url on a catalog or branding resource.

Still stuck? Ask on Flint Help (opens in a new tab)

The canonical image does not exist in the authenticated merchant and environment, or is not attachable.

Fix: Use an untransformed image.url returned for this merchant and environment, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The image dimensions exceed Flint's axis or pixel limits.

Fix: Resize the source to at most 12,000 pixels per axis and 40 megapixels, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The image's dimensions don't fit what this image is for: a merchant icon must be square and at least 128 by 128 pixels.

Fix: Upload a square image at least 128 by 128 pixels, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The image format is unsupported or malformed.

Fix: Provide a valid still JPEG, PNG, or WebP image, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested gallery contains more than eight images.

Fix: Send no more than eight images in the gallery.

Still stuck? Ask on Flint Help (opens in a new tab)

The mutation contains more external image ingestions than one request allows.

Fix: Split the change into mutations containing at most 32 external image sources.

Still stuck? Ask on Flint Help (opens in a new tab)

The prior image ingestion expired and its reserved storage was cleaned up.

Fix: Retry the request with a new idempotency key.

Still stuck? Ask on Flint Help (opens in a new tab)

The same image ingestion step is still running.

Fix: Wait briefly, then retry with the same idempotency key and request body.

Still stuck? Ask on Flint Help (opens in a new tab)

The prior image ingestion attempt ended and cannot be resumed.

Fix: Wait briefly for cleanup, then start a new ingestion with a new idempotency key.

Still stuck? Ask on Flint Help (opens in a new tab)

The image cannot be attached to this resource.

Fix: Use an attachable image returned for the same merchant and environment, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The resource no longer accepts image changes.

Fix: Retrieve the resource and update images only while the resource is mutable.

Still stuck? Ask on Flint Help (opens in a new tab)

The mutation exceeds the total decoded image pixel budget.

Fix: Resize the sources or split the images across smaller mutations.

Still stuck? Ask on Flint Help (opens in a new tab)

Image processing capacity is temporarily exhausted.

Fix: Retry with exponential backoff. If remediation says to start a new ingestion, use a new idempotency key.

Still stuck? Report it with your request ID (opens in a new tab)

The image could not be decoded or processed safely.

Fix: Replace an invalid source. If remediation says to start a new ingestion, use a new idempotency key.

Still stuck? Ask on Flint Help (opens in a new tab)

Image processing exceeded its deadline.

Fix: Retry with exponential backoff and a new idempotency key when remediation says to start a new ingestion.

Still stuck? Report it with your request ID (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The source did not return a complete supported image response.

Fix: Check the source response, redirects, encoding, and content length, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The source URL does not resolve to an allowed public origin.

Fix: Use a public HTTPS origin that does not resolve to private, loopback, link-local, or Flint infrastructure addresses.

Still stuck? Ask on Flint Help (opens in a new tab)

The source host did not return the image before the fetch deadline.

Fix: Retry with exponential backoff and a new idempotency key when remediation says to start a new ingestion, or use a more reliable source host.

Still stuck? Report it with your request ID (opens in a new tab)

The source image exceeds the 5 MB byte limit.

Fix: Reduce the source file below 5 MB, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The source host was temporarily unavailable.

Fix: Retry with exponential backoff and a new idempotency key when remediation says to start a new ingestion.

Still stuck? Report it with your request ID (opens in a new tab)

The image source URL violates Flint's HTTPS source rules.

Fix: Use an HTTPS URL on port 443 without credentials or a fragment.

Still stuck? Ask on Flint Help (opens in a new tab)

The merchant's stored image bytes have reached the configured quota.

Fix: Remove unused image attachments or wait until ready unattached images expire, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The submitted image URL is invalid.

Fix: Use the exact untransformed image.url returned by Flint.

Still stuck? Ask on Flint Help (opens in a new tab)

The image URL is a transformed delivery URL instead of the canonical asset URL.

Fix: Use the exact image.url returned by Flint without a variant path, query, or fragment.

Still stuck? Ask on Flint Help (opens in a new tab)

An active variant does not select one value for each active option.

Fix: Select one active value for each active option on the product.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

An organization settings policy requires this merchant to inherit the setting, so the request cannot set it.

Fix: Remove the setting identified by param from the request, or ask the organization to change its settings policy.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

Instant payouts are not available.

Fix: Create a standard payout instead.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be completed as submitted or in its current state.

Fix: Inspect the error response, correct the request or resource state, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The payment attempt was declined or could not be completed.

Fix: Use the remediation next_actions and retry only after changing the requested payment inputs.

Still stuck? Ask on Flint Help (opens in a new tab)

The API key is missing a required scope.

Fix: Create or use an API key with the required scope, then retry the request.

Still stuck? Ask on Flint Help (opens in a new tab)

Flint returned an internal server error.

Fix: Retry with exponential backoff. Contact support with the request_id if the error persists.

Still stuck? Report it with your request ID (opens in a new tab)

The billing interval count is greater than 365.

Fix: Send a billing_interval_count from 1 through 365.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request action is not supported by this operation.

Fix: Use one of the documented action values and retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The promotion amount_off_money is missing, not positive, or has no currency.

Fix: Send application_method.amount_off_money with a positive amount and a currency.

Still stuck? Ask on Flint Help (opens in a new tab)

A line item's min_unit_price_money is greater than its max_unit_price_money.

Fix: Set min_unit_price_money to an amount less than or equal to max_unit_price_money.

Still stuck? Ask on Flint Help (opens in a new tab)

The API key credential is malformed or invalid.

Fix: Check the API key value or create a new API key, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested API version is not supported.

Fix: Set Flint-Version to a supported version listed in the error details.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The Authorization header is malformed or uses an unsupported credential.

Fix: Send a Flint API key or partner install token as Authorization: Bearer <token>, or use X-API-Key for API keys.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request could not be authenticated.

Fix: Send a valid Flint credential supported by this endpoint, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The billing anchor day is outside the supported range.

Fix: Set billing_anchor_day to a day from 1 through 31.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The offered billing interval options are invalid.

Fix: Provide unique billing_interval and billing_interval_count pairs with supported intervals and positive counts.

Still stuck? Ask on Flint Help (opens in a new tab)

The billing schedule owner is not supported.

Fix: Use flint or external.

Still stuck? Ask on Flint Help (opens in a new tab)

A buy_x_get_y promotion requires discount_class line_item.

Fix: Set discount_class to line_item.

Still stuck? Ask on Flint Help (opens in a new tab)

The buy_x_get_y quantities must be positive.

Fix: Set application_method.buy_min_quantity and application_method.get_quantity to 1 or more.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The business name is null, blank, or longer than 120 characters.

Fix: Send business_name with 1 to 120 characters. Surrounding whitespace is trimmed, and the name cannot be cleared.

Still stuck? Ask on Flint Help (opens in a new tab)

The buyer cancellation timing is not supported.

Fix: Set customer_account.buyer_capabilities.cancellation_timing to end_of_period or buyer_chooses.

Still stuck? Ask on Flint Help (opens in a new tab)

The longest buyer pause is outside the supported range.

Fix: Set customer_account.buyer_capabilities.pause.max_cycles from 1 to 12, or omit it for no limit.

Still stuck? Ask on Flint Help (opens in a new tab)

The consecutive skip limit is outside its allowed range.

Fix: Set customer_account.buyer_capabilities.skip.max_consecutive_skips to an integer from 1 to 12, or omit it for no limit.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The cancellation reason is not in the supported public vocabulary.

Fix: Use requested_by_customer, duplicate, fraudulent, or abandoned as allowed for the caller.

Still stuck? Ask on Flint Help (opens in a new tab)

The cancellation reason code is not a standard code.

Fix: Use too_expensive, missing_features, switched_service, unused, customer_service, too_complex, low_quality, or other.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The requested capture amount is invalid.

Fix: Send a positive amount in the authorization currency, or omit amount_money to capture the available authorization.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

The request payload or query parameters did not pass validation.

Fix: Fix the field identified by the error response, then retry.

Still stuck? Ask on Flint Help (opens in a new tab)

A category is invalid, or the request has more than 100 categories.

Fix: Send no more than 100 categories, each with 1 through 100 characters that include a letter or number.

Still stuck? Ask on Flint Help (opens in a new tab)

The category description is invalid.

Fix: Provide a description with at most 2,048 characters, or omit it.

Still stuck? Ask on Flint Help (opens in a new tab)