---
title: エラー
description: エラーの形式と、API ごとのエラーコードと HTTP ステータスの一覧。
---

外部 API のエラーはどの API でも同じ形式で返ります。処理の分岐には HTTP ステータスと `error.code` を使ってください。同じ `code` でも、API によって HTTP ステータスが違うことがあります。そのため、以下の一覧は API ごとに分けています。

## 形式

エラーの応答は次の形です。

```json 応答
{
  "error": {
    "code": "product_not_found",
    "message": "…",
    "request_id": "…"
  }
}
```

- `code`: エラーの種類を表す値です。処理の分岐にはこの値を使ってください。
- `message`: 人が読むための説明です。
- `request_id`: 問い合わせのときに伝える ID です。秘密情報や内部のエラーの内容は含みません。問い合わせは support@cozeni.net へお願いします。

:::note
権利確認（`POST /customer/entitlements/check`）は、拒否のとき `{ "entitled": false, "reason": "…" }` の形で返ります。この形は上の形式とは異なります。詳しくは、[権利確認](#entitlements) を参照してください。
:::

## 共通のコード

複数の API に共通するコードの意味です。どの API が返すかは、API ごとの表を見てください。

| HTTP | `code` | 意味と対応 |
| --- | --- | --- |
| 400 | `invalid_input` | 入力が正しくありません。未知のフィールド、型や形式の誤り、JSON でない本文を含みます。入力を直して再送してください。 |
| 401 | `unauthorized` | API キーが無効です。失効、期限切れ、キーと接続先の環境が一致しない場合を含みます。キーを確かめてください。 |
| 403 | `insufficient_scope` | キーに必要な権限（スコープ）がありません。必要な権限を付けたキーを発行してください。 |
| 404 | `not_found` | 存在しない API です。パスとメソッドを確かめてください。 |
| 429 | `rate_limited` | 呼び出し回数の上限を超えました。`Retry-After` ヘッダーの秒数を待ってから再試行してください。 |
| 500 | `internal` | Cozeni 側のエラーです。時間をおいて再試行してください。 |
| 503 | `unavailable` | 一時的に処理できません。時間をおいて再試行してください。 |

ここに無いコードが返ることもあります。知らないコードは HTTP ステータスで扱ってください。

## API ごとのエラー

### 管理 API

対象は `GET /account`、`GET` と `POST /products`、`GET` と `PATCH /products/{product_id}`、`PUT` と `DELETE /products/{product_id}/image`、`GET` と `PUT /products/{product_id}/checkout-link` です。

| HTTP | `code` | 返す操作と意味 |
| --- | --- | --- |
| 400 | `invalid_input` | すべての操作。入力が正しくありません。`POST /products` で `Idempotency-Key` ヘッダーが無いか、1〜128文字でない場合も含みます。 |
| 401 | `unauthorized` | すべての操作。API キーが無効です。 |
| 403 | `insufficient_scope` | `GET /account` 以外のすべての操作。必要な権限がありません。各操作に必要な権限は、[API リファレンス](/api-reference) で確かめてください。 |
| 404 | `product_not_found` | 商品を指定する操作。商品が無いか、他の販売者の商品です。どちらも同じ 404 になります。 |
| 404 | `checkout_link_not_found` | `GET /products/{product_id}/checkout-link`。購入リンクがまだ発行されていません。`PUT` で発行します。 |
| 409 | `idempotency_conflict` | `POST /products`。同じ `Idempotency-Key` で、内容の違う入力を送りました。保存したキーと入力を照らし合わせてください。キーを無条件に作り直さないでください。 |
| 409 | `product_archived` | `PUT /products/{product_id}/checkout-link`。商品がアーカイブ済みです。 |
| 409 | `checkout_link_disabled` | `PUT /products/{product_id}/checkout-link`。標準の購入リンクが無効です。Cozeni は無効なリンクを勝手に有効にすることも、別のリンクを発行することもありません。管理画面で状態を確かめてください。 |
| 413 | `image_too_large` | `PUT /products/{product_id}/image`。画像が 5MB（5,242,880 バイト）を超えています。 |
| 415 | `unsupported_image_type` | `PUT /products/{product_id}/image`。JPEG、PNG、WebP 以外の画像です。画像の形式は中身で判定します。 |
| 429 | `rate_limited` | すべての操作。呼び出し回数の上限を超えました。 |
| 500 | `internal` | すべての操作。Cozeni 側のエラーです。 |
| 503 | `unavailable` | すべての操作。一時的に処理できません。 |

### テスト購入（サンドボックス専用）

対象は `POST /products/{product_id}/test-purchase` と `POST /products/{product_id}/test-purchase/refund` です。

| HTTP | `code` | 意味と対応 |
| --- | --- | --- |
| 400 | `invalid_input` | 本文に何かを指定しました。テスト購入の本文は空（`{}`）にします。購入者は指定できません。 |
| 401 | `unauthorized` | API キーが無効です。 |
| 403 | `insufficient_scope` | `products:write` が必要です。 |
| 404 | `not_found` | サンドボックス以外の環境で呼びました。認証より前に返ります。存在しない API と同じ応答です。 |
| 404 | `product_not_found` | 商品が無いか、他の販売者の商品です。 |
| 409 | `creator_not_ready` | 販売できる状態ではありません。応答の `error.blockers` にある `action_url` を開いて、手続きを済ませてください。`blockers` の内容は [販売者の審査](/pricing/account-review) と同じです。 |
| 409 | `product_archived` | 商品がアーカイブ済み、または購入できない状態です。 |
| 409 | `checkout_link_disabled` | 標準の購入リンクが無効です。管理画面で状態を確かめてください。 |
| 429 | `rate_limited` | 呼び出し回数の上限を超えました。 |
| 500 | `internal` | Cozeni 側のエラーです。 |
| 502 | `stripe_error` | テスト決済の Stripe 処理に失敗しました。同じ要求を打ち直せます。 |
| 503 | `unavailable` | 一時的に処理できません。時間をおいて再試行してください。 |

409 の3つのコードはテスト購入の開始だけで返り、返金では返りません。

テスト購入では次の成功応答にも注意してください。

- `200` の `status: "completed"` は購入権があることを示します。決済は行われません。
- `202` の `status: "pending"` はテスト決済を確定したか、処理中であることを示します。購入権ができるまで、同じ要求を打ち直してください。処理中に新たに決済は行われません。
- 返金の `200` の `status: "nothing_to_refund"` は、返金する対象が無いことを示します。エラーではありません。

### 購入画面を作る

対象は `POST /checkout/sessions` です。

| HTTP | `code` | 意味と対応 |
| --- | --- | --- |
| 400 | `invalid_input` | 入力が正しくありません。メールアドレスの形式、`product_id` の欠落、未知のフィールド、JSON でない本文を含みます。 |
| 401 | `unauthorized` | API キーが無効です。 |
| 403 | `insufficient_scope` | `checkouts:write` が必要です。 |
| 404 | `product_not_found` | 商品が無いか、他の販売者の商品です。標準の購入リンクが無い商品もこの 404 になります。 |
| 409 | `creator_not_ready` | 販売できる状態ではありません（審査が未承認、または Stripe が未接続）。この応答に `blockers` は含まれません。販売の状態は `GET /account` で確かめてください。 |
| 409 | `already_purchased` | そのメールアドレスはこの商品を購入済みで、購入の上限に達しています。購入画面に進めず、「購入済み」として扱ってください。 |
| 410 | `product_archived` | 商品がアーカイブ済み、または未公開です。 |
| 410 | `checkout_link_disabled` | 標準の購入リンクが無効です。 |
| 422 | `sandbox_recipient_not_allowed` | サンドボックスで、管理画面のサインインに使うメールアドレス以外を指定しました。 |
| 429 | `rate_limited` | 呼び出し回数の上限を超えました。 |
| 500 | `internal` | Cozeni 側のエラーです。 |

購入画面の作成では、商品がアーカイブ済み・未公開のときと、標準の購入リンクが無効なときに、購入リンクから開く購入画面と同じ HTTP ステータス（410）を返します。`PUT /products/{product_id}/checkout-link` の 409 とは揃えていません。審査の承認と売上の受け取り先の登録が済んでいないときは、`409 creator_not_ready` を返します。

### 機能フラグの照会

対象は `POST /customers/state` です。

| HTTP | `code` | 意味と対応 |
| --- | --- | --- |
| 400 | `invalid_input` | メールアドレスの形式が正しくありません。未知のフィールドや、JSON でない本文を含みます。 |
| 401 | `unauthorized` | API キーが無効です。 |
| 403 | `insufficient_scope` | `customers:read` が必要です。 |
| 429 | `rate_limited` | この API の別の枠を超えました。[レート制限](/api-reference/rate-limits) を参照してください。 |
| 500 | `internal` | Cozeni 側のエラーです。 |

購入者がいない場合や、機能フラグの権利が無い場合は、エラーにはなりません。`200` で `customer_id: null` と空の `feature_flags` を返します。

### 購入者向けの API

権利確認、ハンドオフ、ポータルへのリンクには、ほかの API と応答の形が異なるものがあります。API ごとに分けて示します。

#### ハンドオフの交換

対象は `POST /customer/handoff/exchange` です。コードは60秒以内、1回だけ使えます。

| HTTP | `code` | 意味と対応 |
| --- | --- | --- |
| 400 | `invalid_code` | コードが不正、期限切れ、または使用済みです。区別されません。新しい入場からやり直してください。 |
| 400 | `invalid_input` | 入力が正しくありません。 |
| 429 | `rate_limited` | 呼び出し回数の上限を超えました。`Retry-After` ヘッダーの秒数を待ったあと、コードは有効期限切れになるため同じコードでは再試行せず、新しい入場からやり直してください。 |
| 503 | `unavailable` | 交換の成否を確かめられないことがあります。同じコードでの再取得は保証されません。新しい入場からやり直してください。 |

#### 権利確認 [#entitlements]

対象は `POST /customer/entitlements/check` です。購入者の Cookie は任意です。Cookie が無い場合は `no_session` を返します。

| HTTP | 応答 | 意味と対応 |
| --- | --- | --- |
| 200 | `{ "entitled": true }` | 権利があります。 |
| 200 | `{ "entitled": false, "reason": "no_grant" }` | 購入していないか、商品が見つかりません。 |
| 200 | `{ "entitled": false, "reason": "revoked" }` | 権利が取り消されています。全額返金された注文などが該当します。 |
| 401 | `{ "entitled": false, "reason": "no_session" }` | 購入者の入場が無い、無効、期限切れ、またはセッションが失効しています。 |
| 400 | 共通のエラーの形（`error.code` が `invalid_input`） | 入力が正しくありません。拒否として扱ってください。 |
| 503 | `{ "entitled": false, "reason": "unavailable" }` | 権利を判定できませんでした。拒否として扱い、時間をおいて再度確認してください。 |

- `no_grant`、`revoked`、`no_session` の拒否には、商品 ID の形式が正しい場合に限り、`enter_url`（入場画面の URL）が付くことがあります。
- `unavailable` には `enter_url` は付きません。障害を再認証の要求に変えないためです。
- 判定できないときは、コンテンツを返さないでください。

#### ポータルへのリンク

対象は `POST /customer/portal-link` です。購入者の Cookie が必要です。

| HTTP | `code` | 意味と対応 |
| --- | --- | --- |
| 401 | `no_session` | 購入者の Cookie が無い、不正、期限切れ、ログアウト後、または購入者が存在しません。 |
| 403 | `forbidden` | ブラウザからの直接呼び出し（`Origin` ヘッダー付き）は許可されていません。販売者のサーバーから呼び出してください。 |
| 503 | `unavailable` | リンクを発行できませんでした。時間をおいて再試行してください。 |

この API の応答は共通のエラーの形です。権利確認の `{ "entitled": …, "reason": … }` の形ではありません。

### CLI の API

CLI の API は `cozeni login` によるログインで使います。対象は `POST /cli/device-codes`、`POST /cli/tokens`、`POST /cli/logout` です。

#### ログインの確認（`POST /cli/tokens`）

ログインの確認は承認を待つあいだ繰り返し呼びます。承認前のエラーは次の `code` で返ります。

| HTTP | `code` | 意味と対応 |
| --- | --- | --- |
| 400 | `authorization_pending` | まだ承認されていません。`interval`（5秒）以上の間隔を空けて、同じ `device_code` で再度確認します。 |
| 400 | `slow_down` | 前回の確認との間隔が短すぎます。サーバーの判定には1秒の猶予がありますが、`interval`（5秒）以上空けて再確認してください。 |
| 400 | `access_denied` | ブラウザで承認が拒否されました。ログインをやり直します。 |
| 400 | `expired_token` | コードが期限切れ、使用済み、または不明です。ログインを最初からやり直します。 |
| 400 | `invalid_input` | 入力が正しくありません。 |
| 429 | `rate_limited` | 呼び出し回数の上限を超えました。`Retry-After` の秒数を待ってください。 |
| 500 | `internal` | Cozeni 側のエラーです。 |

#### コードの発行（`POST /cli/device-codes`）

| HTTP | `code` | 意味と対応 |
| --- | --- | --- |
| 400 | `invalid_input` | 入力が正しくありません。`client_name` と `cli_version` の長さや、使える文字を確かめてください。 |
| 429 | `rate_limited` | 呼び出し回数の上限を超えました。`Retry-After` の秒数を待ってください。 |
| 500 | `internal` | Cozeni 側のエラーです。 |

#### ログアウト（`POST /cli/logout`）

成功は `204` です。応答の本文はありません。キーが無効、失効済み、または不明でも `204` を返し、何もしません。

| HTTP | `code` | 意味と対応 |
| --- | --- | --- |
| 429 | `rate_limited` | 呼び出し回数の上限を超えました。`Retry-After` の秒数を待ってください。 |
| 500 | `internal` | Cozeni 側のエラーです。 |

## 再試行の方法

- `429`：`Retry-After` ヘッダーの秒数を待ってから再送します。
- `500` と `503`：時間をおいて再送します。`POST` では、同じ入力と同じ `Idempotency-Key` で再送します。ただし、購入者の入場コードの交換で `503 unavailable` が返ったときは、再送せず、新しい入場からやり直します。
- テスト購入の `502`（`stripe_error`）：同じ要求を打ち直せます。
- 商品の作成（`POST /products`）で応答を受け取れなかった場合は、保存した同じ入力と同じ `Idempotency-Key` で再送します。新しい商品を作る意思がないのに、キーを作り直さないでください。
