コンテンツにスキップ
Docs
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

エラー

エラーの形式と、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 で再送します。新しい商品を作る意思がないのに、キーを作り直さないでください。

このページは役に立ちましたか?