Errors and retries: Subscriptions docs

Every refusal has the same shape: a code to branch on, a plain-English message, and a failure field that says what a retry would do.

Error response

{
  "error": {
    "code": "SUBSCRIPTION_NOT_FOUND",
    "message": "The selected subscription is not available for this customer.",
    "failure": "permanent"
  }
}

What a retry does

failure	Meaning	What to do
`permanent`	The same request fails the same way until something changes.	Don't retry as is. Fix the request or read the subscription again.
`temporary`	It may work later.	Retry later with the same Idempotency-Key.
(absent)	The outcome is unknown: the change may or may not have happened.	Read the subscription before you retry.

HTTP statuses

Status	When
401	API_KEY_REQUIRED, API_KEY_INVALID
403	API_KEY_SCOPE_REQUIRED, PERMISSION_REQUIRED (the teammate lost access or permission), CUSTOMER_SUBSCRIPTION_ACTION_NOT_ALLOWED
404	Any code ending in _NOT_FOUND, such as CUSTOMER_NOT_FOUND or SUBSCRIPTION_NOT_FOUND
422	Codes starting with INVALID_, IDEMPOTENCY_KEY_REQUIRED, CUSTOMER_QUERY_REQUIRED, PRODUCT_QUERY_REQUIRED, and INVALID_REQUEST when a field is missing
409	The request is valid, but the subscription's current state refuses it
503	A temporary failure, such as Shopify being unavailable. Try again later.

Common codes

Code	What it means
`INVALID_REQUEST`	A required field is missing. The message names it.
`CUSTOMER_NOT_FOUND`	No customer with that customer_id in this workspace.
`SUBSCRIPTION_NOT_FOUND`	The subscription isn't this customer's, or isn't a Chargezen and Shopify subscription.
`INVALID_BILLING_OCCURRENCE`	The order named for order now or a next-order change is no longer the right one. Read upcoming orders again.
`CANNOT_REMOVE_LAST_SUBSCRIPTION_LINE`	A subscription keeps at least one item. Cancel it instead.
`SUBSCRIPTION_SWAP_PRICE_CHANGED`	The replacement's price or quantity changed since you listed swap options. List them again.
`SUBSCRIPTION_SWAP_OPTION_UNAVAILABLE`	The replacement isn't offered anymore. Choose another one.
`ORDER_NOW_PAYMENT_FAILED`	The payment for order now didn't go through. Nothing was charged.
`SUBSCRIPTION_SELECTION_STALE`	The plan or price changed since you listed plans. Nothing was created; list plans again.
`CUSTOMER_SUBSCRIPTIONS_UNAVAILABLE`	Chargezen couldn't read the subscription's details. It's temporary; try again.

Branch on the code, show the message

Write your logic against code. The message is written for people to read.

Errors and retries

What a retry does

HTTP statuses

Common codes

Related Articles

Authentication and keys

Changing subscriptions