Error codes

When an API error includes an error.code value, use this reference to decide whether to correct request data, satisfy a precondition, refresh resource state, or retry the same request. For the full error response shape, HTTP status guidance, type, cause, and fix_code fields, see Errors.

Applications

Error code	Where	Action
application_create_failed	Create application	The application was not created. Review the request, retry once, then contact support with the request id if it still fails.
application_lookup_failed	Lookup application	Application details could not be read. Retry the same request; contact support with the request id if it persists.
application_update_failed	Update application	The application was not changed. Retry the same request; contact support with the request id if it persists.

API keys

Error code	Where	Action
invalid_secret_key_request	Page, lookup, update, revoke, lookup usage	Correct the key id, pagination values, or other documented fields before retrying.
secret_key_generation_failed	Generate	No usable key token was returned. Submit a new generation request; contact support if it continues to fail.
secret_key_not_found	Lookup, update, revoke, lookup usage	Verify the key ID.
secret_key_read_failed	Page, lookup, update, revoke, lookup usage	Key data could not be read. Retry the same request; contact support with the request id if it persists.
secret_key_request_failed	Secret key endpoints	The request failed for an unclassified reason. Retry once, then contact support with the request id if it persists.

Chimes

Error code	Where	Action
chime_broadcast_already_canceled	Cancel broadcast	The broadcast is already canceled. Treat its current state as the result; no retry is needed.
chime_broadcast_already_completed	Cancel broadcast	The broadcast already completed and can no longer be canceled.
chime_broadcast_cancel_failed	Cancel broadcast	Fetch the broadcast before retrying; retry only if its current state still allows cancellation.
chime_broadcast_failed	Broadcast Chimes	Transient broadcast creation failure. Retry the same request with the same idempotency key.
chime_broadcast_lookup_failed	Lookup broadcast	The broadcast could not be read. Retry the same request; contact support with the request id if it persists.
chime_broadcast_not_found	Lookup, cancel broadcast	Verify the broadcast ID.
chime_lookup_failed	Lookup Chime	The Chime could not be read. Retry the same request; contact support with the request id if it persists.
chime_not_found	Lookup Chime	Verify the Chime ID.
chime_page_failed	Page Chimes	The Chime page could not be read. Retry the same page request.
chime_schedule_already_canceled	Cancel schedule	The schedule is already canceled. Treat its current state as the result; no retry is needed.
chime_schedule_already_completed	Cancel schedule	The scheduled send already completed and can no longer be canceled.
chime_schedule_cancel_failed	Cancel schedule	Fetch the schedule before retrying; retry only if its current state still allows cancellation.
chime_schedule_lookup_failed	Lookup schedule	The schedule could not be read. Retry the same request; contact support with the request id if it persists.
chime_schedule_not_found	Lookup, cancel schedule	Verify the schedule ID.
chime_schedule_failed	Schedule Chime	Transient schedule creation failure. Retry the same request with the same idempotency key.
chime_send_failed	Send Chime	Transient send failure. Retry the same request with the same idempotency key.
email_message_unsafe	Send Chime	Supplied email content failed safety validation. Update the sender, headers, links, text, or HTML before retrying.
email_recipient_suppressed	Send Chime	The email recipient is suppressed from delivery. Use a different recipient or resolve the suppression first.
invalid_recipient	Send Chime	The recipient did not resolve to a supported SMS or email address. Fix the inline contact or customer record.
invalid_chime_broadcast_request	Broadcast Chimes	Correct the audience or message content before retrying.
invalid_chime_request	Send Chime	Correct the recipient or message content before retrying.
invalid_chime_schedule_request	Schedule Chime	Correct the recipient, message content, or delivery time before retrying.
message_template_archived	Send, Schedule, Broadcast	The stored template is archived. Use an active template or create a replacement.
message_template_attachments_unsupported	Send, Schedule, Broadcast	The email template rendered attachments, but Chimes cannot deliver template attachments yet. Remove attachments before sending.
message_template_channel_mismatch	Send, Schedule, Broadcast	The stored template channel does not match the recipient transport. Use an SMS template for SMS recipients or an email template for email recipients.
message_template_email_subject_empty	Send, Schedule, Broadcast	The email template rendered an empty subject. Update the template or variables.
message_template_email_text_empty	Send, Schedule, Broadcast	The email template rendered an empty text body. Update the template or variables.
message_template_email_unsafe	Send, Schedule, Broadcast	Rendered email content failed Chime safety validation. Update template content, links, headers, sender, or variables.
message_template_id_required	Send, Schedule, Broadcast	message_template.template_id is missing or blank. Provide the stored template id.
message_template_not_found	Send, Schedule, Broadcast	No visible template matched message_template.template_id. Verify the id and application.
message_template_not_published	Send, Schedule, Broadcast	The stored template has no published version. Publish it before using it for sends.
message_template_render_too_long	Send, Schedule, Broadcast	Rendered content exceeds the transport limit. Shorten the template or variables.
message_template_render_unsafe	Send, Schedule, Broadcast	The template renderer rejected unsafe email output. Update the template or variables.
message_template_required	Send, Schedule, Broadcast	A stored template reference was expected but omitted. Provide message_template with template_id.
message_template_sms_empty	Send, Schedule, Broadcast	The SMS template rendered no body text. Update the template or variables.
message_template_variables_invalid	Send, Schedule, Broadcast	Variables do not match the published template contract. Supply required variables with valid types.
missing_message_content	Send, Schedule, Broadcast	No content source matched the recipient transport. Provide full_message, email, or message_template as appropriate.
mixed_message_content	Send, Schedule, Broadcast	The request mixed SMS and email content. Provide one content source for the resolved transport.

Customers

Error code	Where	Action
customer_not_found	Lookup customer	Verify the customer_id.

File APIs

Direct uploads and file access

Error code	Where	Action
empty_file	Upload file	Supply a file containing at least one byte.
file_api_unavailable	File endpoints	A required file operation is temporarily unavailable. Retry later.
file_content_type_not_allowed	Upload file	Use a MIME type allowed for the selected purpose.
file_contents_unavailable	Download file contents	The stored file cannot be read. Contact support if the error persists.
file_extension_not_allowed	Upload file	Use a filename extension allowed for the selected purpose.
file_has_live_references	Delete file	Remove live Inttegro references before deleting the file.
file_metadata_unavailable	File endpoints	File metadata is temporarily unavailable. Retry later.
file_not_found	Lookup, download, delete	Verify the file ID.
file_operation_failed	File endpoints	The operation could not complete. Retry later; contact support if it persists.
file_purpose_not_allowed	Upload file	Use one of the documented file purposes.
file_row_limit_exceeded	Upload file	Reduce a product-import CSV to no more than 10,000 data rows.
file_schema_mismatch	Upload file	Make the product-import CSV match the documented column schema.
file_storage_encoding_unsupported	Download file contents	The stored representation cannot be delivered. Contact support.
file_too_large	Upload file	Reduce the file to the selected purpose's size limit.
idempotency_key_conflict	Upload file	Use the original upload input with this key or choose a new key.
idempotency_key_in_progress	Delete file	The original deletion is still processing. Retry with the same key.
idempotency_key_unsupported	Upload file	Send the retry key in the Idempotency-Key header, not a form field.
idempotency_storage_unavailable	Delete file	Retry the deletion later with the same key.
image_metadata_unreadable	Upload file	Supply a valid image whose dimensions can be read.
storage_quota_exceeded	Upload file	Free file capacity or request a higher allocation.

File links

Error code	Where	Action
file_contents_unavailable	Open file link	The stored file cannot be read. Contact support if the error persists.
file_link_access_denied	Open file link	Open the link from an allowed origin and client address.
file_link_access_limit_reached	Open file link	Create a new link if the recipient still needs access.
file_link_already_exists	Create file link	Submit a new create request; contact support if the error repeats.
file_link_delivery_invalid	Create or open file link	Correct the delivery, download, origin, or CIDR settings.
file_link_expired	Open file link	Create a new link with a future expiry.
file_link_inactive	Open file link	Create a new link if access should resume.
file_link_not_found	Create, lookup, revoke, open	Verify the file-link ID or use the complete URL returned by create.
file_link_operation_failed	File-link endpoints	The operation could not complete. Retry later; contact support if it persists.
file_link_purpose_not_allowed	Create file link	Use file links only for a linkable file purpose.
file_metadata_unavailable	File-link endpoints	File metadata is temporarily unavailable. Retry later.
file_storage_encoding_unsupported	Open file link	The stored representation cannot be delivered. Contact support.
idempotency_key_conflict	Revoke file link	Use the original revoke input with this key or choose a new key.
idempotency_key_in_progress	Revoke file link	The original revocation is still processing. Retry with the same key.
idempotency_storage_unavailable	Revoke file link	Retry the revocation later with the same key.

Upload requests

Error code	Where	Action
empty_file	Fulfill upload request	Supply a file containing at least one byte.
file_api_unavailable	Upload-request endpoints	A required file operation is temporarily unavailable. Retry later.
file_content_type_not_allowed	Fulfill upload request	Upload a MIME type allowed by the request and its purpose.
file_extension_not_allowed	Fulfill upload request	Upload a filename extension allowed by the request and its purpose.
file_metadata_unavailable	Upload-request endpoints	File metadata is temporarily unavailable. Retry later.
file_name_mismatch	Fulfill upload request	Use the exact filename required by the request.
file_row_limit_exceeded	Fulfill upload request	Reduce a product-import CSV to no more than 10,000 data rows.
file_schema_mismatch	Fulfill upload request	Make the product-import CSV match the documented column schema.
file_size_mismatch	Fulfill upload request	Upload a file with the exact required byte size.
file_too_large	Fulfill upload request	Reduce the file to the request's maximum size.
file_too_small	Fulfill upload request	Upload a file that meets the request's minimum size.
idempotency_key_conflict	Create or cancel upload request	Use the original input with this key or choose a new key.
idempotency_key_in_progress	Create or cancel upload request	The original action is still processing. Retry with the same key.
idempotency_storage_unavailable	Create or cancel upload request	Retry the action later with the same key.
image_metadata_unreadable	Fulfill upload request	Supply a valid image whose dimensions can be read.
storage_quota_exceeded	Fulfill upload request	Free file capacity or request a higher allocation.
upload_request_already_exists	Create upload request	Submit a new create request; contact support if the error repeats.
upload_request_attempt_limit_reached	Fulfill upload request	Create a replacement request if another upload should be allowed.
upload_request_expired	Fulfill upload request	Create a replacement request with a future expiry.
upload_request_expiry_invalid	Create upload request	Set expires_at to a future RFC 3339 timestamp.
upload_request_inactive	Fulfill upload request	Create a replacement request if uploading should resume.
upload_request_not_found	Lookup, cancel, fulfill	Verify the ID or use the complete URL returned by create.
upload_request_operation_failed	Create, lookup, page, cancel	Retry later; contact support if the error persists.
upload_request_policy_invalid	Create upload request	Keep constraints within the selected purpose and use valid size relationships.
upload_request_state_conflict	Cancel upload request	Refresh the request and act only while its current state permits cancellation.
upload_request_upload_failed	Fulfill upload request	Retry later if attempts remain; contact support if the error persists.

Financial accounts

Error code	Where	Action
fa_is_payout_dest	Disconnect a financial account	Remove or replace this account as a payout destination before disconnecting it.

Message templates

Error code	Where	Action
message_template_archived	Update, Publish, Render preview	Use an active template or create a replacement.
message_template_create_failed	Create	Transient create failure. Retry the same request.
message_template_invalid	Create, Update	Update the template fields, channel content, or variable declarations.
message_template_not_found	Update, Publish, Archive, Lookup, Page, Render preview	Verify the template ID.
message_template_not_published	Render preview	Publish the template before rendering the published version or using it in Chimes.
message_template_render_invalid	Render preview	Fix invalid variables or template syntax.
message_template_render_too_long	Render preview	Shorten the template or variable values so rendered content fits the transport limit.
message_template_render_unsafe	Render preview	Update rendered email content, links, headers, sender, or variables so the safety scan passes.
message_template_request_invalid	All message template endpoints	Correct the request shape, unknown fields, or missing required values.
message_template_update_failed	Update, Publish, Archive	Transient mutation failure. Retry the same request.

One-time passwords

Error code	Where	Action
invalid_otp_initiation_request	Initiate OTP	Correct the recipient, message, token, duration, or gateway fields before retrying.
otp_already_verified	Verify OTP	Treat the transaction as verified; do not submit another token.
otp_idempotency_key_already_used	Initiate OTP	Look up the existing transaction. Use a new key only for a deliberate new OTP transaction.
otp_initiation_failed	Initiate OTP	The transaction did not start successfully. Retry the same request.
otp_lookup_failed	Lookup OTP	The transaction could not be read. Retry the same request; contact support with the request id if it persists.
otp_max_verification_attempts_exceeded	Verify OTP	Start a new transaction; the current transaction cannot accept another token.
otp_token_size_invalid	Initiate OTP	Set token_size to a value from 5 through 10.
otp_transaction_canceled	Verify OTP	Start a new transaction; canceled transactions cannot accept verification attempts.
otp_transaction_expired	Verify OTP	Start a new transaction and verify its token before it expires.
otp_transaction_not_found	Lookup OTP	Verify the transaction ID.
otp_verification_failed	Verify OTP	Fetch the transaction before deciding whether another attempt is allowed; contact support if the failure persists.

Orders

Error code	Where	Action
confirmation_already_satisfied	Confirm payment	Fetch the order and inspect the latest payment status; the confirmation has already completed.
confirmation_bad_token	Confirm payment	Ask the customer for the latest token and retry the confirmation.
confirmation_expired	Confirm payment	Request a new confirmation before retrying.
confirmation_failed	Confirm payment	Verify the token from the active confirmation request and retry.
confirmation_max_reached	Confirm payment	Request a new confirmation; the current request has no remaining attempts.
confirmation_not_found	Confirm payment	Verify that the confirmation belongs to this order payment.
confirmation_not_needed	Request confirmation	Refresh order state; this payment does not currently require customer confirmation.
confirmation_pending	Pay, Confirm payment	Wait for the customer to finish confirmation or send a new confirmation request before retrying.
confirmation_request_failed	Create, Pay, Request confirmation	Transient confirmation delivery failure. Retry the same request.
customer_not_found	Page	Verify the customer filter before paging orders.
draft_mode_order_has_no_invoice	Send invoice	Finalize the draft order before sending its hosted invoice link.
invalid_line_items	Create, Update	Fix the line_items payload and retry.
order_canceled	Update, Cancel	Fetch the order state; canceled orders cannot be changed or canceled again.
order_completed	Update, Complete	Completed orders cannot be changed or completed again.
order_customer_invalid	Create, Pay	Provide a valid customer_id or valid customer_data.
order_delivery_auth_failed	Send invoice, Send receipt	Retry with valid Inttegro API credentials for the order application.
order_delivery_contact_missing	Send invoice, Send receipt	Add an email address or phone number to the order customer before sending the document link.
order_delivery_failed	Send invoice, Send receipt	Delivery failed for every available contact method. Retry the same request.
order_expired	Update, Cancel	Use an order that is still active, or create a new order.
order_finalize_failed	Create	The order was created but finalization did not complete. Fetch the order before deciding whether to retry.
order_finalize_required	Update	Include an explicit finalize decision when changing seal-sensitive fields.
order_line_item_limit_exceeded	Create, Update	Reduce the order to 64 line items or fewer. Contact support if you need this limit increased.
order_not_found	Pay, Confirm payment, Request confirmation, Update, Finalize, Complete, Lookup, Cancel, Lookup invoice, Send invoice, Send receipt	Verify the order_id.
order_not_payable	Pay	Fetch the latest order state; only payable orders can accept payment.
order_paid	Pay, Update, Complete	Fetch the order state; paid orders cannot be paid or edited again.
order_payment_create_failed	Create	Transient payment creation failure. Retry the same request.
order_payment_execution_failed	Create	The order was created, but immediate payment did not complete. Fetch the order and payment before retrying payment.
order_payment_missing	Pay, Complete	Attach or create the payment required by this operation before retrying.
order_total_limit_exceeded	Create, Update	Reduce the order total below the currency limit. Contact support if you need this limit increased.
order_payment_not_paid	Complete	Complete the order only after its payment succeeds or is marked paid out of band.
order_payment_touched	Update	The payment has entered confirmation or execution; avoid changing payment-sensitive order fields.
order_receipt_number_invalid	Create, Update	Provide a non-empty receipt number that differs from the current value.
order_receipt_missing	Send receipt	Send a receipt only after the order is paid.
order_terminated	Pay, Cancel	Use a non-terminal order; paid, completed, canceled, or expired orders cannot use this operation.
order_update_empty	Update	Include at least one order field to change.
orders_page_unavailable	Page	Transient page loading failure. Retry the same request.
payment_cant_pay_offline	Pay, Complete	Mark paid out of band only when the payment supports that action in its current state.
payment_method_invalid	Create, Pay, Update	Use an active payment method that belongs to the order customer.
payment_refresh_failed	Create, Pay, Confirm payment	Transient payment refresh failure. Retry the same request after fetching the latest order state.
payment_transition_conflict	Create, Pay, Confirm payment, Complete	Another operation updated or claimed the payment first. Commerce stopped this request to prevent a duplicate attempt or an overwrite of a newer result. Fetch the latest order or payment before deciding what to do next.
price_archived	Create	Use an active price or create an inline price for the order.
price_inactive	Create	Activate the price or choose an active price.
price_not_found	Create	Verify the price_id in the line item.
product_archived	Create	Use an active product or create the line item inline.
product_not_found	Create	Verify the product_id in the line item.
purchase_intent_already_used	Create	Create the order from a purchase intent that has not already been claimed.
unprocessable_request	Lookup, Update	Refresh state and retry after checking the request parameters.

Handling payment_transition_conflict

This HTTP 409 means Commerce rejected a payment transition because another operation reached the payment first. It is not a payment decline and does not prove that the payment failed. Read the latest payment state, then stop if it is paid, follow next_action if customer action is required, wait if processing is still underway, or offer a deliberate new attempt if the latest state is failed. See the complete error reference for the decision guide and example response.

Payment methods

Error code	Where	Action
payment_method_already_active	Activate, Update	The payment method is already active; no activation retry is needed.
payment_method_already_archived	Archive, Update	The payment method is already archived; no archive retry is needed.
payment_method_already_inactive	Deactivate, Update	The payment method is already inactive; no deactivation retry is needed.
payment_method_archived	Activate, Archive, Deactivate, Update	Unarchive the payment method before updating or reusing it.
payment_method_conflicting_state_updates	Update	Send only one state transition in a single update request.
payment_method_inactive	Payment method mutations	Activate the payment method before reusing it.
payment_method_no_updates	Update	Include at least one supported field to change.
payment_method_not_archived	Unarchive, Update	Only archived payment methods can be unarchived.
payment_method_not_found	Lookup, Update, Archive, Unarchive, Activate, Deactivate	Verify the payment_method_id.
payment_method_owner_address_country_required	Update	Include owner.address.country when adding an owner address.

Purchase intents

Error code	Where	Action
invalid_purchase_intent_quantity_range	Create, Update	Set the minimum quantity to at least 1 and the maximum quantity to at least the minimum.
purchase_intent_already_used	Cancel, Create order	The single-use Buy link has already created an order. Use that order or create a new purchase intent.
purchase_intent_invalid	Lookup, Update	Replace the purchase intent because its configured price no longer belongs to its product.
purchase_intent_not_found	Lookup, Page, Update, Cancel	Verify the purchase intent ID.
purchase_intent_price_not_found	Create	Verify price_id and choose a price from your catalog.
purchase_intent_price_product_mismatch	Create	Choose a price that belongs to the selected product.
purchase_intent_price_unavailable	Create, Lookup, Page, Update	Use or restore an active, unarchived price; replace the purchase intent if its configured price cannot be used.
purchase_intent_product_not_found	Create	Verify product_id and choose a product from your catalog.
purchase_intent_product_unavailable	Create, Lookup, Page, Update	Use or restore a product available for sale; replace the purchase intent if its product cannot be used.

Prices

Error code	Where	Action
cannot_change_price_amount	Update	Create a new price when the amount or currency needs to change.
cannot_change_product_id	Update	Create a new price for a different product association.
default_price_cannot_deactivate	Deactivate	Set another default unit price on the product before deactivating this price.
price_already_active	Activate	The price is already active; no activation retry is needed.
price_already_archived	Archive	The price is already archived; no archive retry is needed.
price_already_inactive	Deactivate	The price is already inactive; no deactivation retry is needed.
price_archived	Activate, Deactivate	Use a non-archived price or create a replacement.
price_create_failed	Create	Transient price creation failure. Retry the same request.
price_not_found	Lookup, Update, Activate, Deactivate, Archive	Verify the price_id.
product_not_found	Create	Verify the product_id before creating the price.

Products

Error code	Where	Action
cannot_clear_field_once_set	Update	Replace the field with a new value instead of clearing it.
cannot_update_immutable_field	Update	Remove immutable fields such as id, app_id, created_at, and type from the request.
invalid_product_type	Update	Use a supported product type.
product_add_price_failed	Add price	Transient price attachment failure. Retry the same request.
product_already_archived	Archive	The product is already archived; no archive retry is needed.
product_already_published	Publish	The product is already published; no publish retry is needed.
product_already_unpublished	Unpublish	The product is already unpublished; no unpublish retry is needed.
product_archived	Add price, Set default unit price	Unarchive or recreate the product before changing prices.
product_not_found	Lookup, Add price, Set default unit price, Update, Publish, Unpublish, Archive	Verify the product_id.

Refunds

Error code	Where	Action
invalid_refund	Create	Correct the refund request parameters and try again.
refund_amount_exceeds_line_item	Create	Reduce refund_amount to the selected line item's remaining refundable amount.
refund_cancel_failed	Cancel	Fetch the refund, then retry the same idempotent request with backoff only if it is still pending.
refund_cannot_cancel	Cancel	Fetch the latest refund. Only a pending refund that has not started processing can be canceled.
refund_capacity_changed	Create	Another refund changed the remaining refundable amount. Fetch current refunds and recalculate before retrying.
refund_create_failed	Create	Retry the same idempotent request with backoff.
refund_currency_mismatch	Create	Use the currency recorded on each selected order line item.
refund_customer_unavailable	Create	Refund an order that has an owning customer, or contact support if the customer should be present.
refund_duplicate_line_item	Create	Include each order_line_item_id only once.
refund_insufficient_merchant_balance	Create	Wait until enough merchant funds are available before retrying.
refund_line_item_not_found	Create	Verify every order_line_item_id belongs to the specified order.
refund_merchant_balance_unavailable	Create	Retry after merchant funds become available; contact support if the balance should already be usable.
refund_not_found	Lookup, Cancel	Verify refund_id.
refund_order_not_found	Create	Verify order_id.
refund_order_not_paid	Create	Wait until the order payment succeeds before creating a refund.
refund_original_payment_method_unavailable	Create	Contact support to determine whether another refund route is available.
refund_page_unavailable	Page	Retry the same request with backoff.
refund_paid_allocation_unavailable	Create	Contact support because the paid amount cannot be assigned safely to the selected line items.