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.

---

Chimes

Error code	Where	Action
chime_broadcast_failed	Broadcast Chimes	Transient broadcast creation failure. Retry the same request with the same idempotency key.
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.
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 and application ownership.

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 Commerce 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 and application ownership.
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 and application ownership.
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.

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 Commerce 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_not_found	Pay, Confirm payment, Request confirmation, Update, Finalize, Complete, Lookup, Cancel, Lookup invoice, Send invoice, Send receipt	Verify the order_id and application ownership.
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_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	Fetch the latest order or payment state before deciding whether another request is needed.
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.

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 and application ownership.
payment_method_owner_address_country_required	Update	Include owner.address.country when adding an owner address.

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 and application ownership.
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 and application ownership.