For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Paddle Docs home

Error reference

A list of all the errors that you can encounter when working with the Paddle API. Learn more about a particular error and get information about how to troubleshoot.

How errors work

The Paddle API uses standard HTTP response codes to let you know when something's wrong. It also returns some useful information to help you troubleshoot.

When you encounter an error, the API returns an error object rather than a data object or array. Validation errors include an errors array with details of each invalid field.

If you're having trouble, include the request_id in the response when contacting support.

Learn more about errors in the API reference →

Error
{
  "error": {
    "type": "request_error",
    "code": "not_found",
    "detail": "Product pro_01ghbk4xjn4qdsmstcwzgcgg35 not found.",
    "documentation_url": "https://developer.paddle.com/errors/shared/not_found"
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000000"
  }
}
Validation error
{
  "error": {
    "type": "request_error",
    "code": "invalid_field",
    "detail": "Request does not pass validation.",
    "documentation_url": "https://developer.paddle.com/errors/shared/invalid_field",
    "errors": [
      {
        "field": "active",
        "message": "must be provided as part of the request"
      },
      {
        "field": "description",
        "message": "maximum length of 256 exceeded. provided value length 653"
      }
    ]
  },
  "meta": {
    "request_id": "00000000-0000-0000-0000-000000000000"
  }
}

Generic

General errors that can occur across the API.

authentication_malformedauthentication_missingbad_gatewaybad_requestconcurrent_modificationconflictentity_archivedforbiddeninternal_errorinvalid_client_tokeninvalid_fieldinvalid_jsoninvalid_time_query_parameterinvalid_tokeninvalid_urlmethod_not_allowednot_available_in_sandboxnot_foundnot_implementedpaddle_billing_not_enabledreceipt_data_not_enabledrequest_body_too_largerequest_headers_too_largeservice_unavailabletemporarily_unavailabletoo_many_requestsunexpected_request_bodyunsupported_media_type

Addresses

Encountered when working with address entities.

address_location_not_allowed

Adjustments

Encountered when creating or working with transaction adjustments.

adjustment_amount_above_remaining_allowedadjustment_amount_cannot_be_zeroadjustment_invalid_combination_of_typesadjustment_invalid_credit_actionadjustment_no_tax_available_to_adjustadjustment_payout_earnings_cannot_be_zeroadjustment_pending_refund_requestadjustment_tax_mode_not_allowedadjustment_total_amount_above_remaining_allowedadjustment_transaction_customer_mismatchadjustment_transaction_invalid_status_for_creditadjustment_transaction_invalid_status_for_refundadjustment_transaction_item_has_already_been_fully_adjustedadjustment_transaction_item_invalidadjustment_transaction_item_over_adjustmentadjustment_transaction_missing_customer_idadjustment_transaction_subscription_mismatchadjustment_transaction_without_captured_payment

Businesses

Encountered when working with business entities on a customer.

business_contact_email_domain_not_allowed

Checkout domains

Encountered when working with checkout domain entities.

checkout_domain_apple_pay_domain_verification_failedcheckout_domain_domain_not_approvedcheckout_domain_payment_method_verification_service_unavailable

Currencies

Encountered when working with currencies or currency-related settings.

currency_code_invalidcurrency_codes_invalidcurrency_primary_balance_invalid

Customers

Encountered when working with customer entities.

customer_already_existscustomer_email_domain_not_allowedcustomer_email_invalid

Discounts

Encountered when working with discount entities.

discount_code_conflictdiscount_expireddiscount_group_name_conflictdiscount_maximum_recurring_intervals_greater_than_maximumdiscount_restricted_product_not_activediscount_restricted_product_price_not_activediscount_usage_limit_exceededdiscount_usage_limit_less_than_times_used

Metrics

Encountered when working with the metrics discovery and Explore endpoints.

invalid_aggregationinvalid_cursorinvalid_operatormax_lookback_exceededquery_timeouttoo_many_datapointsunknown_entityunknown_field

Notifications

Encountered when working with notification and webhook entities.

email_notification_setting_incorrectnotification_cannot_replaynotification_maximum_active_settings_reachednotification_replay_invalid_origin_typenotification_setting_cannot_be_duplicatenotification_simulation_already_running_conflictnotification_simulation_run_configuration_conflictnotification_simulation_run_notification_settings_conflicturl_notification_setting_incorrect

Payment methods

Encountered when working with saved payment method entities.

payment_method_in_use

Prices

Encountered when working with price entities.

price_billing_cycle_frequency_below_1price_billing_cycle_frequency_greater_than_maximumprice_duplicate_currency_override_for_countryprice_quantity_maximum_greater_than_maximumprice_quantity_minimum_greater_than_maximumprice_trial_period_frequency_below_1price_trial_period_frequency_greater_than_maximumprice_trial_period_missing_fieldsprice_trial_period_requires_billing_cycletrial_currency_mismatchtrial_is_either_paid_or_cardless

Products

Encountered when working with product entities.

product_tax_category_not_approved

Reports

Encountered when working with report entities.

concurrent_report_generation_not_allowedreport_creation_limit_exceededreport_emptyreport_expiredreport_failedreport_not_ready

Subscriptions

Encountered when working with subscription entities.

subscription_address_not_suitable_for_collection_modesubscription_all_items_removedsubscription_archived_discount_application_attemptsubscription_billing_details_requiredsubscription_cannot_activatesubscription_cannot_be_pausedsubscription_charge_duplicate_price_idssubscription_consent_granted_too_earlysubscription_continuing_existing_billing_period_not_allowedsubscription_continuing_existing_billing_period_not_allowed_subscription_past_duesubscription_credit_creation_against_processing_transactionsubscription_credit_creation_against_uncompleted_transaction_not_allowedsubscription_currency_code_incompatible_with_payment_method_providersubscription_currency_code_not_valid_for_manualsubscription_currency_update_and_actions_creating_credits_not_allowedsubscription_currency_update_not_allowedsubscription_customer_email_domain_not_allowedsubscription_customer_not_suitable_for_collection_modesubscription_discount_not_valid_for_itemssubscription_duplicate_price_idssubscription_immediate_charge_24_hour_limit_exceededsubscription_immediate_charge_hour_limit_exceededsubscription_incorrect_proration_on_paused_subscriptionsubscription_invalid_billing_mode_for_scheduled_changesubscription_invalid_discount_currencysubscription_is_canceled_action_invalidsubscription_is_inactive_action_invalidsubscription_items_update_missing_proration_billing_modesubscription_locked_consent_review_periodsubscription_locked_pending_changessubscription_locked_processingsubscription_locked_renewalsubscription_manual_collection_mode_activation_not_allowedsubscription_maximum_number_of_line_items_reachedsubscription_missing_payment_method_cannot_activatesubscription_missing_payment_method_cannot_resumesubscription_missing_payment_method_cannot_retry_paymentsubscription_missing_payment_method_cannot_updatesubscription_must_be_pausedsubscription_new_items_not_validsubscription_next_billed_at_too_soonsubscription_no_recurring_items_remainsubscription_not_activesubscription_not_automatic_collectionsubscription_one_off_discount_not_validsubscription_only_update_items_on_paused_subscriptionsubscription_outstanding_pending_refundsubscription_outstanding_transactionsubscription_payment_declinedsubscription_payment_provider_unavailablesubscription_price_not_foundsubscription_product_tax_category_not_approvedsubscription_quantity_missing_for_new_itemssubscription_quantity_not_validsubscription_scheduled_change_invalid_updatesubscription_trialing_discount_update_invalid_optionssubscription_trialing_items_update_invalid_optionssubscription_update_causing_customer_mismatch_not_allowedsubscription_update_different_currency_creditssubscription_update_transaction_balance_less_than_charge_limitsubscription_update_when_canceledsubscription_update_when_past_duesubscription_update_when_trialing

Transactions

Encountered when working with transaction entities.

transaction_address_not_suitable_for_collection_modetransaction_address_region_or_city_already_settransaction_adjusted_unable_to_revisetransaction_balance_less_than_charge_limittransaction_billing_details_must_be_nulltransaction_billing_details_object_requiredtransaction_billing_period_starts_at_greater_than_nowtransaction_both_price_id_and_object_foundtransaction_cannot_be_modified_and_canceledtransaction_cannot_be_revised_with_invalid_tax_identifiertransaction_cannot_be_revised_with_tax_higher_than_grand_total_or_negative_taxtransaction_cannot_provide_both_discount_code_and_idtransaction_checkout_not_enabledtransaction_checkout_url_domain_is_not_approvedtransaction_creation_blockedtransaction_currency_code_not_valid_for_manualtransaction_custom_data_numeric_value_too_largetransaction_customer_is_required_for_business_validationtransaction_customer_is_required_with_addresstransaction_customer_not_suitable_for_collection_modetransaction_default_checkout_url_not_settransaction_discount_not_eligibletransaction_discount_not_foundtransaction_duplicate_price_idstransaction_immutabletransaction_immutable_while_processing_paymenttransaction_invalid_discount_currencytransaction_invalid_status_changetransaction_invalid_status_to_revisetransaction_item_quantity_out_of_rangetransaction_maximum_number_of_line_items_reachedtransaction_not_ready_cannot_process_paymenttransaction_nothing_to_revisetransaction_payment_method_change_field_immutabletransaction_payment_terms_frequency_greater_than_maximumtransaction_payment_terms_object_requiredtransaction_payout_account_requiredtransaction_preview_adjustment_subscription_conflicttransaction_price_different_billing_cycletransaction_price_different_trial_periodtransaction_price_not_foundtransaction_product_not_foundtransaction_recurring_balance_less_than_charge_limittransaction_requires_currency_code_for_custom_discounttransaction_revise_missing_business_nametransaction_revised_limit_reachedtransaction_status_must_be_ready