Skip to main content
Back to Developer changelog

Tags:

  • Admin GraphQL API
  • 2026-04

Subscriptions APIs: new payment error code and error classification

We’ve added new payment error codes for subscription billing attempts in the GraphQL Admin API. These new error codes provide more granularity and consistency, making payment errors easier to diagnose. They’re currently available in the unstable API version, will be released in version 2026-04.

We’re also updating our error-code mapping to be more explicit:

  • In the unstable version, you’ll start seeing new error codes display, along with fewer AUTHENTICATION_ERROR and PAYMENT_METHOD_DECLINED errors.
  • If you’re on version 2026-01 or earlier, you might still notice a shift in error volumes across existing error codes. We improved our mapping so that some errors previously categorized as generic decline errors, such as PAYMENT_METHOD_DECLINED, are now mapped more explicitly to existing error codes. For example, we can map more cases to INSUFFICIENT_FUNDS instead of generic declines.

Known issue resolved

From January 28, 2026, to February 4, 2026, there was a temporary issue with error mapping, which might have caused a surge in TRANSIENT_ERROR. This has been fixed.

Error code mapping

  • If you're on version unstable or 2026-04, you'll see the new error code.

  • If you're on 2026-01 or earlier versions, you'll see the currently mapped code.

    New error codeCurrently mapped error code
    AMOUNT_TOO_LARGEUNEXPECTED_ERROR
    MERCHANT_ACCOUNT_ERRORUNEXPECTED_ERROR
    AUTHENTICATION_FAILEDAUTHENTICATION_ERROR
    AUTHENTICATION_REQUIREDAUTHENTICATION_ERROR
    CALL_ISSUERPAYMENT_METHOD_DECLINED
    CARD_DECLINEDPAYMENT_METHOD_DECLINED
    CONFIRMATION_REJECTEDPAYMENT_METHOD_DECLINED
    DO_NOT_HONORPAYMENT_METHOD_DECLINED
    MERCHANT_RULEPAYMENT_METHOD_DECLINED
    OFF_SESSION_REJECTEDPAYMENT_METHOD_DECLINED
    RETRY_DECLINEDPAYMENT_METHOD_DECLINED
    TRANSACTION_LIMIT_EXCEEDEDPAYMENT_METHOD_DECLINED
    INCORRECT_ZIPINVALID_PAYMENT_METHOD
    INVALID_CURRENCYINVALID_PAYMENT_METHOD
    INVALID_NUMBERINVALID_PAYMENT_METHOD
    INVALID_PAYMENT_ERRORINVALID_PAYMENT_METHOD
    PAYMENT_METHOD_UNSUPPORTEDINVALID_PAYMENT_METHOD
    INCORRECT_ADDRESSINVALID_PAYMENT_METHOD
    INCORRECT_NUMBERCARD_NUMBER_INCORRECT
    EXPIRED_CARDEXPIRED_PAYMENT_METHOD
    INVALID_EXPIRY_DATEEXPIRED_PAYMENT_METHOD
    EXPIRED_BUYER_ACTIONEXPIRED_PAYMENT_METHOD
    PROCESSING_ERRORUNEXPECTED_ERROR
    PAYMENT_PROVIDER_ERRORUNEXPECTED_ERROR
    GENERIC_ERRORTRANSIENT_ERROR
    CANCELLED_PAYMENTBUYER_CANCELED_PAYMENT_METHOD
    INVALID_PURCHASE_TYPEPURCHASE_TYPE_NOT_SUPPORTED
Was this section helpful?