--- title: "Error codes" description: "Look up Inttegro API error codes and the corrective action for each code." canonical: "https://studio.inttegro.com/api/error-codes" format: inttegro-machine-docs/v1 language: "Ruby" sdk_version: "v10.0.0" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/ruby/readers/index.json" reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations." preamble_estimated_tokens: 431 model_token_report: "https://studio.inttegro.com/machine/token-report.json" preamble_questions: 5 preamble_source: "machine-only-decisions" recommended_mcp_tools: [] estimated_tokens: 15935 token_estimate_method: "utf8_bytes_divided_by_4" --- ## Machine preamble **Summary:** Look up Inttegro API error codes and the corrective action for each code. This Ruby representation uses the selected SDK's native names wherever Studio has a verified mapping. ### Five questions #### Q1. Is Error codes the right source for this task? Use this reference for look up inttegro api error codes and the corrective action for each code. Keep the four decision rules below with its exact operations and fields; do not infer a broader workflow from endpoint order. #### Q2. What is the first decision rule for resolve an error code in the context of the failed operation? Match the exact error code and operation in this catalog, then apply its stated action. Similar names across resources do not imply the same recovery or retry safety. #### Q3. What is the second decision rule for resolve an error code in the context of the failed operation? Read [Errors](https://studio.inttegro.com/machine/ruby/api/errors.md) first when the response shape, error type, fix code, cause, or request ID is needed. HTTP status alone is not specific enough to choose a business recovery path. #### Q4. What is the third decision rule for resolve an error code in the context of the failed operation? A conflict or uncertain write usually requires a fresh resource lookup before retrying. If the operation supports idempotency, reuse the original key and payload for the same logical action. #### Q5. What is the fourth decision rule for resolve an error code in the context of the failed operation? Preserve the request ID for support and observability, but do not show raw internal diagnostics to customers. Convert the verified recovery state into a clear customer-facing action. ## Document content # 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](https://studio.inttegro.com/machine/ruby/api/errors.md). ## Resolve an error code in the context of the failed operation The four decision rules are in the machine preamble above. ## 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`](https://studio.inttegro.com/machine/ruby/e/payment_transition_conflict.md) | 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](https://studio.inttegro.com/machine/ruby/e/payment_transition_conflict.md) 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. |