---
title: "Errors and retries: Subscriptions docs | Chargezen"
description: "How the Subscriptions REST API reports refusals: the error shape, HTTP statuses, common codes, and when a retry is safe."
url: "https://chargezen.com/docs/subscriptions/api/errors"
lang: "en"
updated: "2026-11-09"
---

Canonical URL: https://chargezen.com/docs/subscriptions/api/errors

# Errors and retries

How the Subscriptions REST API reports refusals: the error shape, HTTP statuses, common codes, and when a retry is safe.

Last updated: 2026-11-09

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

```json
{
  "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.

### Related Articles

[

#### Authentication and keys

Idempotency-Key and refused keys



](https://chargezen.com/docs/subscriptions/api/authentication)[

#### Changing subscriptions

Every change and what it takes



](https://chargezen.com/docs/subscriptions/api/changing-subscriptions)

Was this page helpful?

Need more help? [Contact support](https://chargezen.com/docs/checkoutos/troubleshooting/support)