エラー
エラーの形式と、API ごとのエラーコードと HTTP ステータスの一覧。
外部 API のエラーはどの API でも同じ形式で返ります。処理の分岐には HTTP ステータスと error.code を使ってください。同じ code でも、API によって HTTP ステータスが違うことがあります。そのため、以下の一覧は API ごとに分けています。
形式
エラーの応答は次の形です。
{
"error": {
"code": "product_not_found",
"message": "…",
"request_id": "…"
}
}
code: エラーの種類を表す値です。処理の分岐にはこの値を使ってください。message: 人が読むための説明です。request_id: 問い合わせのときに伝える ID です。秘密情報や内部のエラーの内容は含みません。問い合わせは support@cozeni.net へお願いします。
共通のコード
複数の 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 リファレンス で確かめてください。 |
| 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 の内容は 販売者の審査 と同じです。 |
| 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 の別の枠を超えました。レート制限 を参照してください。 |
| 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 |
交換の成否を確かめられないことがあります。同じコードでの再取得は保証されません。新しい入場からやり直してください。 |
権利確認
対象は 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で再送します。新しい商品を作る意思がないのに、キーを作り直さないでください。