エラー

対象

このAPIは、Roktネットワーク上で構築する統合パートナー向けです。Roktのeコマースパートナーで、自分のチェックアウトにプレースメントを統合する場合は、代わりにRokt Ecommerce開発者ドキュメントを使用してください。

Partnerships APIからのすべてのエラーレスポンスは、成功レスポンスと同じ形のJSONエンベロープを使用しますが、errorが埋められ、data: nullとなります。このページは、各ステータスが何を意味するのか、それを引き起こすシナリオ、そして目の前にある予期しないレスポンスをデバッグする方法のリファレンスです。

レスポンスエンベロープレスポンスエンベロープへの直接リンク

すべてのレスポンス（成功とエラー）はこの形をしています：

{
  "status": 400,
  "error": "BadRequest",
  "message": "store_identifier https://acme is not a valid URL",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": null
}

statusinteger

HTTPステータスコードを反映します（成功時は200、エラー時は400/401/403/404/409/422/5xx）。

errorstring | null

HTTPステータスに対応した安定したエラーコード：例 BadRequest (400), Unauthorized (401), Forbidden (403), NotFound (404), Conflict (409), ValidationFailed (422), RateLimitExceeded (429), InternalServerError (500)。切り替えに安全です。成功時はnull。

messagestring

何が問題だったのかを人間が読める形で説明（成功時は"ok"）。内部オペレーターに表示するのは安全ですが、エンドマーチャントにそのまま表示しないでください。

request_idstring

サーバー生成の相関ID（UUID）。また、X-Request-Idレスポンスヘッダーにも返されます。これをRoktサポートに渡すことで、サーバー側のログを呼び出しに基づいて調べることができます。

dataobject | array | null

成功時のエンドポイント固有のペイロード。エラー時はnull。

ヒント

レスポンスエンベロープから常にrequest_idをキャプチャしてください。サポートチケットに含めることが迅速な解決のための最大の手段です。

HTTPステータスコードHTTPステータスコードへの直接リンク

ステータス	意味	呼び出し側のアクション
400 Bad Request	検証に失敗、ペイロードが不正、必要なボディフィールドが欠落	ペイロードを修正し、新しい`Idempotency-Key`で再試行
401 Unauthorized	APIトークンが欠落、期限切れ、または無効	トークン発行統合を通じてAPIトークンを更新
403 Forbidden	APIトークンは有効ですが、(a) あなたがそのアカウントで行動する権限がないか（プラットフォームのアカウント間の許可設定が欠落しているか同期されていない）、または (b) あなたの`X-Platform-Parent-Account-Id`が管理アカウントの実際の親と一致しない	オペレーションに通知：マネージャー管理の許可が取り消された可能性があるか、ヘッダーの値が間違っています
404 Not Found	リソースが存在しないか、呼び出し側がアクセスできない	`account_id`を確認し、それがマネージャー管理の範囲内にあることを確認
409 Conflict	`Idempotency-Key`の競合、または`store_identifier`が他のパートナーによってすでに登録されている	下記の一般的なシナリオを参照
422 Unprocessable Entity	必要なヘッダーが欠落している（最も一般的には書き込み時の`X-Platform-Parent-Account-Id`）、またはペイロードが意味的に無効（例：不明な列挙値）	欠落しているヘッダーを追加し、同じキーで再試行
429 Too Many Requests	パートナーごとのレート制限に達した	`Retry-After`を遵守し、同じ `Idempotency-Key`で再試行。エンドポイントごとの制限についてはレート制限を参照
500 Internal Server Error	Rokt側のエラー	待機して同じ `Idempotency-Key`で再試行
501 Not Implemented	`Prefer: respond-async`を送信しましたが、非同期モードはまだプラットフォームで有効になっていません	ヘッダーを削除
502 / 503 / 504	Rokt側の一時的なエラー（下流サービスの不調）	バックオフして再試行、同じ `Idempotency-Key`

警告

5xx レスポンスの場合、常に元々使用した同じ Idempotency-Key で再試行してください。24時間の重複排除ウィンドウ内で行います。再試行時に新しいキーを使用すると、元の操作がサーバー側で最終的に成功した場合、同じ論理操作が2回実行される可能性があります。

一般的なエラーシナリオ一般的なエラーシナリオへの直接リンク

422: add-pagesが重複するサーフェスで422を返す（409ではない）

POST /accounts/{account_id}/pages（add-pages）を呼び出す際、同じサーフェスのページが既にアカウントに存在する場合、エンドポイントは現在422を返し、409ではありません。add-pagesからの422を重複するサーフェスの可能性として扱い、GET /accountsを介して既存のページを確認するか、元の登録応答からpages[].page_identifierの値を確認してください。

422: ヘッダーX-Platform-Parent-Account-Idが必要です

書き込み呼び出しでX-Platform-Parent-Account-Idヘッダーを省略しました。サーバーはすべての書き込みでそれを必要とします。

{
  "status": 422,
  "error": "ValidationFailed",
  "message": "header X-Platform-Parent-Account-Id is required",
  "request_id": "0e3a1b9c-...",
  "data": null
}

修正方法。 リクエストにX-Platform-Parent-Account-Id: <your-rokt-parent-account-id>を追加します。同じIdempotency-Keyで再試行してください。24時間の重複排除ウィンドウ内でサーバーは再試行をまとめます。

400: store_identifierが有効なURLではありません

store_identifierは、スキームを含む3から400文字の完全修飾URLでなければなりません。ホスト名のみの送信は拒否されます。

{
  "status": 400,
  "error": "BadRequest",
  "message": "store_identifier acme.myshopify.com is not a valid URL",
  "request_id": "0e3a1b9c-...",
  "data": null
}

修正方法。 https://acme.myshopify.com（または商人の主要なストアフロントURL）を送信します。新しいIdempotency-Keyで再試行してください。

400: 次のパートナーバーティカルに対するバーティカルマッピングが見つかりません（MCL PUTで）

blockedVerticals配列には、バーティカルマッピングに対応する行がないバーティカルまたはサブバーティカルペアが含まれています。サーバーはそれをRoktの内部分類法に変換できないため、PUT全体がアトミックに拒否されます：部分的な書き込みはありません。

メッセージには見つかったすべてのマッピングされていないペアがリストされているため、配列を二分して違反者を見つける必要はありません。

{
  "status": 400,
  "error": "BadRequest",
  "message": "No vertical mapping found for the following partner vertical(s): (partner_vertical_id=1500, partner_sub_vertical_id=1610). Call GET /v1/partnership/vertical-mappings to see which verticals are currently mapped, and contact smb-partnerships@rokt.com to request additions. The MCL write was rejected atomically; no partial update was applied.",
  "request_id": "0e3a1b9c-...",
  "data": null
}

修正方法。 GET /v1/partnership/vertical-mappings?parent_account_id=<your-parent>を呼び出し、メッセージに名前が付けられたペアを戻ってきたものと比較します（マッピングされているものを確認するを参照）。smb-partnerships@rokt.comにpartnerVerticalId / partnerSubVerticalIdの値とカテゴリ名をメールして行を追加してもらいます。それらが追加されるまで、PUTからマッピングされていないペアを省略してください。

400: このバーティカルはまだマッピングされていません（登録時）

vertical_id / sub_vertical_idペアをPOST /v1/accounts/register/partnershipに送信しましたが、バーティカルマッピングに行がありません。登録は商人アカウントが作成される前に失敗するため、部分的なアカウントをクリーンアップする必要はありません。

{
  "status": 400,
  "error": "BadRequest",
  "message": "This vertical isn't mapped yet (vertical_id=1500, sub_vertical_id=1610). Contact smb-partnerships@rokt.com to have it mapped.",
  "request_id": "0e3a1b9c-...",
  "data": null
}

修正方法。 親アカウントにシードされているものを確認します（マッピングされているものを確認するを参照）、その後、ペアとカテゴリ名をsmb-partnerships@rokt.comにメールします。

すべての登録呼び出しがこの方法で失敗する場合、1行が欠けているのではなく、何もシードされていません。その場合、GETは空の配列を返します。

409: Roktアカウントは既に存在します（登録時）

別のパートナープラットフォームがこのstore_identifierを既に所有しています。Roktアカウントは存在しますが、別の統合に接続されています。登録は所有権を自動的に移行できません。

{
  "status": 409,
  "error": "Conflict",
  "message": "Rokt Account already exists",
  "request_id": "0e3a1b9c-...",
  "data": null
}

修正方法。 この正確なメッセージをオンボーディングUIで商人に表示します：

アカウント作成に関する問題があり、さらなる確認が必要です。 [パートナープラットフォームサポート]にメールしてください。

この問題を回避するためにstore_identifierを変更して再試行しないでください。この競合は、システムが実際の所有権の問題を人間が解決する必要があることを示しています。

400: 必須の非空パラメータIdempotency-Keyがありません

すべての書き込み呼び出し（POST、PUT）には、Idempotency-Key ヘッダーが必要です。これは空でないUUIDでなければなりません。

{
  "status": 400,
  "error": "BadRequest",
  "message": "Idempotency-Key header required for partnership writes",
  "request_id": "0e3a1b9c-...",
  "data": null
}

修正。 クライアント側で論理操作ごとにUUIDを生成し、それを Idempotency-Key: <uuid> として渡します。リトライ時にキーをどのようにスコープするかについては、Idempotency Keys を参照してください。

409: 操作が進行中 / Idempotency-Key ボディの不一致

元の呼び出しがまだ処理中であるか、キャッシュされたものとは異なるボディで Idempotency-Key を再利用しました。サーバーは同じキーを同時に2回実行せず、新しいペイロードでキャッシュされた応答を静かに上書きしません。

修正。 少し待って同じ呼び出しを再試行するか、より良い方法として、操作を直接ポーリングします：

curl https://accounts.rokt.com/v1/partnership/operations/$OPERATION_ID \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT"

operation_id はすべての書き込みで X-Operation-Id 応答ヘッダーに返されます。Operations を参照してください。

429: レート制限を超えました（Retry-After を遵守）

このエンドポイントのパートナーごとのレート制限を超えました。サーバーは標準のエンベロープとともに、再試行する前に待つべき秒数を持つ Retry-After 応答ヘッダーを返します。

{
  "status": 429,
  "error": "RateLimitExceeded",
  "message": "rate limit exceeded for partnership writes; retry after 30s",
  "request_id": "0e3a1b9c-...",
  "data": null
}

応答ヘッダー（関連するサブセット）：

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-Request-Id: 0e3a1b9c-1234-4abc-9def-aaaabbbbcccc

修正。 Retry-After 秒間スリープし、元々使用した同じ Idempotency-Key で再試行します。24時間の重複排除ウィンドウ内でキーを再利用することで、サーバーはリトライを単一の論理操作にまとめます。ここで新しいキーを使用すると、元の操作がサーバー側で最終的に成功した場合に書き込みを2回実行するリスクがあります。

curl バックオフスニペット（ヘッダーをファイルに書き込み、Retry-After を解析し、スリープし、同じキーで再試行）：

KEY=$(uuidgen)
while true; do
  STATUS=$(curl -s -o body.json -D headers.txt -w '%{http_code}' \
    -X PUT https://accounts.rokt.com/v1/partnership/accounts/$ACCOUNT_ID/status \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-Platform-Parent-Account-Id: $PARENT" \
    -H "Idempotency-Key: $KEY" \
    -H "Content-Type: application/json" \
    -d '{ "status": "active" }')
  if [ "$STATUS" != "429" ]; then break; fi
  WAIT=$(grep -i '^Retry-After:' headers.txt | awk '{print $2}' | tr -d '\r')
  sleep "${WAIT:-30}"
done

Python 等価（requests を使用）：

import time, uuid, requests

key = str(uuid.uuid4())
while True:
    r = requests.put(
        f"https://accounts.rokt.com/v1/partnership/accounts/{account_id}/status",
        headers={
            "Authorization": f"Bearer {token}",
            "X-Platform-Parent-Account-Id": parent,
            "Idempotency-Key": key,  # same key across retries
            "Content-Type": "application/json",
        },
        json={"status": "active"},
    )
    if r.status_code != 429:
        break
    time.sleep(int(r.headers.get("Retry-After", "30")))

エンドポイントごとの制限については Rate Limits を、より広範なリトライ契約については Handling Failures を参照してください。

400: contact は hosted_invite 支払い設定にのみ有効です

experience: "embedded" と contact ブロックを一緒に送信しました。これら2つは相互に排他的です：contact は hosted_invite に必要であり、embedded には禁止されています。

修正。 embedded の場合は contact フィールドを削除するか、Rokt がマーチャントにメールを送信することを望む場合は experience を hosted_invite に変更します。

フィールドレベルのバリデーションエラーフィールドレベルのバリデーションエラーへの直接リンク

初期オンボーディング時に統合を妨げる一般的なフィールドごとのルールです。完全なスキーマは openapi.yaml にありますが、ここでは知っておくべき制約の短いリストを示します。

`POST /v1/accounts/register/partnership`post-v1accountsregisterpartnership への直接リンク

フィールド	ルール
`brand`	必須、1–200文字
`country_code`	必須、正確に2文字（ISO 3166-1 alpha-2）。小文字の入力はサーバー側で大文字に正規化されます
`store_identifier`	必須、有効なURL（`https://` のようなスキームを含む必要があります）、3–400文字
`external_account_id`	必須、空でない。登録のための冪等性キー；再利用すると同じ `account_id` が返されます
`vertical_id` / `sub_vertical_id`	必須。パートナーの分類値であり、Roktのものではありません。両方とも垂直マッピングに行が必要です；Check what's mapped で確認してください
`platform_parent_account_id`	必須のボディフィールド。明確にするために `X-Platform-Parent-Account-Id` ヘッダーにミラーリングします

`PUT .../marketplacecontrolslists`put-marketplacecontrolslists への直接リンク

フィールド	ルール
`name`	必須、空でない文字列
`blockedVerticals`	必須の配列。各エントリは `partnerVerticalId` + `partnerSubVerticalId` を含む必要があります。`policy` は省略された場合、デフォルトで `Block` になります
`blockedVerticals[].policy`	`Allow` または `Block` のいずれか
`blockedVerticals[].position1Policy`	オプション。`Allow` または `Block` のいずれか。省略された場合、エントリの `policy` がデフォルトになります
`domains[].policy`	`Allow` または `Block` のいずれか

`PUT .../status`put-status への直接リンク

フィールド	ルール
`status`	必須。`active` または `paused` のいずれか。注意: `mixed` は読み取り専用の集約状態であり、送信することはできません

`POST .../payout-setup`post-payout-setup への直接リンク

フィールド	ルール
`provider`	必須。現在は `stripe_connect` のみサポートされています
`experience`	必須。`embedded` または `hosted_invite` のいずれか。`contact` と相互排他的; 以下を参照
`contact.email`	`hosted_invite` には必須。`embedded` には禁止。 `contact` を `experience: "embedded"` と共に送信すると 400 を返します
任意のネストされた `bank` / `card` / `routing` / `account_number` / `iban` / `ssn` / `tax` / `tax_id` / `external_account*` / `payout_destination` / `payment_method` / `cvc` フィールド	リクエスト内のどこでも禁止。 400 を返します。Stripe はこのデータを直接商人から収集します

デバッグチェックリストデバッグチェックリストへの直接リンク

予期しないエラーに直面したときは、サポートに連絡する前に、このリストを上から下まで確認してください。

レスポンスエンベロープから request_id をキャプチャします（または X-Request-Id レスポンスヘッダー; 同じ値）。
すべての書き込み呼び出しに Content-Type: application/json が設定されていることを確認します。
すべての書き込みに X-Platform-Parent-Account-Id が設定されていることを確認します; 422 はそれが欠けていることを示す標準信号です。
API トークンをデコードして、有効期限が切れていないことを確認します（exp クレーム）。API トークンは短い TTL です: 約 5 分。
accounts.rokt.com/v1/partnership/* または accounts.rokt.com/v1/accounts/register/partnership にアクセスしていることを確認します。他の Rokt ホストはパートナーコール可能ではありません。
書き込みが 4xx を返すがサーバーのバグを疑う場合は、?dry_run=true を使用して再試行し、ペイロードに問題があるのかサーバーにあるのかを特定します。ドライランは状態を保持せずに完全な検証を実行します。ドライランモードを参照してください。
任意の垂直マッピング 400 については、GET /v1/partnership/vertical-mappings?parent_account_id=<your-parent> を呼び出します（マッピングされているものを確認を参照）。空の配列は何もシードされていないことを意味します; 非空のものにペアが欠けている場合は、単一の行が欠けています。
5xx レスポンスについては、24 時間の重複排除ウィンドウ内で同じ Idempotency-Key を使用して再試行します。再試行時に新しいキーを生成しないでください。
すべてが失敗した場合は、smb-partnerships@rokt.com に request_id、呼び出しの概算タイムスタンプ（UTC）、およびアクセスしたエンドポイントをメールで送信してください。

備考

なぜ request_id が重要なのか。 Roktは、サーバーサイドのログエントリに対して、あなたの呼び出しに関連するすべてのエントリにこれを通します。サポートチケットにこれを渡すことで、チームはトラフィックをページングすることなく、正確な障害を見つけることができます。

レスポンスエンベロープレスポンスエンベロープ への直接リンク

HTTPステータスコードHTTPステータスコード への直接リンク

一般的なエラーシナリオ一般的なエラーシナリオ への直接リンク

フィールドレベルのバリデーションエラーフィールドレベルのバリデーションエラー への直接リンク

POST /v1/accounts/register/partnershippost-v1accountsregisterpartnership への直接リンク

PUT .../marketplacecontrolslistsput-marketplacecontrolslists への直接リンク

PUT .../statusput-status への直接リンク

POST .../payout-setuppost-payout-setup への直接リンク

デバッグチェックリストデバッグチェックリスト への直接リンク