エラーコード

Listings API の HTTP ステータスコード、Listings と Social の SYxxxxx エラーコード、および v4 API が返す 3 種類のエラーレスポンス形式です。

Listings API は、標準的な HTTP ステータスコードでリクエストの結果を報告します。エラーコードには SY というプレフィックスが付き、エラーの message 文字列内に SYxxxxx: <human-readable reason> の形式で含まれます。

HTTP ステータスコード

3 種類のレスポンス形式

以下の各セクションに示すように、ほとんどの失敗では、トップレベルまたは操作の結果内にネストされた errors 配列が返されます。一部の失敗では、代わりに単一の error オブジェクトが返されます。該当するのは、レート制限（429）と、一部のリクエストレベルの失敗（INTERNAL_SERVER_ERROR などの code を伴う 400/500）です。両方を確認してください。errors は配列で、error はオブジェクトです。

1. リクエストレベル：トップレベルの errors[]

認証、認可、リクエストの形式不正による失敗では、操作が実行される前に処理が中断されます。対応する 4xx ステータス（上記）とともに、レスポンスのトップレベルにエラーが返されます。

{  "data": { "createLocation": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

2. 書き込み検証：ネストされた data.<operation>.errors[]

作成、更新、公開のリクエストは、それ以外の点で形式が正しければ、HTTP 200 を返します。入力がビジネスルールに違反している場合、失敗は data.<operation>.errors 内の操作固有のペイロード配下にネストされた形で報告されます。成功時にもこの配列は存在しますが、空です（"errors": []）。

{  "data": {    "createLocation": {      "errors": [        { "message": "SY10126: City is Mandatory" },        { "message": "SY10010: state_iso" }      ],      "location": null    }  }}

3. ゲートウェイレベル：トップレベルの単一の error オブジェクト

レート制限や予期しないゲートウェイ障害が発生すると、変換前に処理が中断され、code、message、correlation_id を含む 1 つの error オブジェクトが返されます。429 の本文については、下記の rate_limited を参照してください。

書き込みでは、値が格納された data.<operation> オブジェクトを伴う 200 であっても、必ず data.<operation>.errors を確認してください。書き込みは部分的に失敗し、その失敗がここで報告される場合があります。

402 Payment Required レスポンスには error ラッパーがありません。code、message、doc_url と、支払いが必要な請求書がある場合の pay_url は、トップレベルに配置されます。下記の payment_required を参照してください。

書き込みの再試行には注意が必要

v4 API は Idempotency-Key をサポートしていません。ヘッダーは無視され、繰り返された書き込みを検出するエンドポイントもありません。タイムアウトしたり 5xx を返したりした作成、更新、公開の呼び出しでも、サーバー上ではすでに確定している可能性があるため、確認せずに再試行すると、拠点、投稿、レビューへの返信が重複して作成される場合があります。

読み取りは、バックオフを使用して自由に再試行できます。書き込みの場合は、まず読み取って確認してください。自分で管理できるキー（storeId、店舗コード、インタラクションの返信リスト）を使ってレコードを検索し、実際に存在しない場合にのみ呼び出しを繰り返してください。

一般的なコード

SY10xxxの範囲の検証コードは特定の入力フィールドに対応し、messageには検証に失敗したフィールド名またはルールが示されます。SY90xxxの範囲の認証・認可コードはリクエスト単位のもので、対応するステータスとともにトップレベルで返されます。

接続済みアカウントのコード

SY810xxの範囲のコードは、掲載先の掲載情報をインポートまたはリンクするConnected Accountsエンドポイントから返されます。これらはHTTP 200のレスポンスボディ内にネストされた状態で返されるため（上記のレスポンス形式2）、ステータスが成功を示していてもdata.<operation>.errorsを確認してください。

Socialのコード

SY950xxの範囲のコードは、ブランド、接続、ソーシャル投稿を扱うSocialエンドポイントから返されます。接続済みアカウントのコードと同様に、HTTP 200のレスポンスボディ内にネストされて返されるため、ステータスが成功を示していても、data.<operation>.error（一括処理ルートではdata.<operation>.errorsも）を確認してください。

SY95042とSY95044は利用権限に関するエラーであり、入力エラーではありません。プランを変更せずに再試行しても、同じエラーで失敗します。SY95045、SY95046、SY95049、SY95052は入力エラーであり、次のリクエストで修正できます。

Listingsの利用権限コード

rate_limited

429 Too Many Requests: アカウントがプランのレート制限を超えました。本文は標準のエラーレスポンスで、retry_after_secondsのヒント、サポートへの問い合わせ時に記載するcorrelation_id、およびこのセクションへのリンクを含むdoc_urlが含まれます。

{  "error": {    "code": "RATE_LIMITED",    "message": "Too many requests. Slow down.",    "retry_after_seconds": 30,    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited"  }}

retry_after_seconds（または、Retry-Afterヘッダーがある場合はその値）で指定された時間だけ待ち、指数バックオフで再試行してください。プランごとの制限とバックオフの参考実装については、レート制限を参照してください。

payment_required

402: このアカウントの直近の支払いが失敗したため、すべての/api/v4エンドポイントが一時停止されています。未払いの請求書のStripeページが利用可能な場合は、本文にそのページを示すpay_urlが含まれ、X-Error-Codeレスポンスヘッダーにも同じcodeが含まれます。引き続きダッシュボードの請求ページを開いて支払うことができます。

{  "code": "payment_required",  "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.",  "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc",  "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}

未決済の請求書がすべて支払われると、1分以内にアクセスが復旧します。最初の支払い失敗から3日後も請求書が未払いの場合、Listingsのサブスクリプションが解約され、アカウントの拠点がアーカイブされます。アカウントに有効なSocialのサブスクリプションもある場合は、Socialへのアクセスが維持されます。それ以外の場合は、アカウントが閉鎖され、APIキーが機能しなくなります。

social_payment_required

402: Socialのサブスクリプションの直近の支払いが失敗したため、Socialのエンドポイント（/api/v4/social/*）が一時停止されています。Listingsのエンドポイントは引き続き機能します。本文にはpayment_requiredと同じフィールドが含まれ、"code": "social_payment_required"が設定されます。最初の支払い失敗から3日後も請求書が未払いの場合、Socialのサブスクリプションが解約され、アカウントのブランドがアーカイブされます。Listingsのサブスクリプションがないアカウントは閉鎖され、APIキーが機能しなくなります。

開発者ポータルのコントロールプレーンのエラー

開発者ポータルのアカウントおよびキー管理用エンドポイント（ダッシュボード自体のAPIルート）は、上記のRESTのerrors[]形式とは異なる、単一の構造化されたエラーレスポンスを返します。各codeには、correlation_idと、このページの該当セクションへのリンクを含むdoc_urlが含まれます。

{  "error": {    "code": "AUTH_INVALID_KEY",    "message": "Session is invalid or expired.",    "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c",    "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key"  }}

auth_missing_key

401: 認証情報が提供されていません。再度サインインするか、キーをAuthorization: API <your-key>として送信してください。

auth_invalid_key

401: セッションまたはキーが無効であるか、有効期限が切れています。再認証するか、ダッシュボードからキーを再発行してください。

auth_insufficient_scope

403: 認証情報は有効ですが、この操作は許可されていません。読み取りスコープのキーでは書き込み用エンドポイントを呼び出せないため、必要に応じて書き込み用のキーを発行してください。

not_found

404: リクエストされたリソース、またはIDで指定されたリソースが存在しません。

conflict

409: リクエストがリソースの現在の状態と競合しています（すでに失効しているキーを失効させようとした場合など）。

validation_failed

422: リクエストボディの検証に失敗しました。レスポンスのfieldとdetailsに、問題のある入力が示されます。

internal_error

500: サーバー側で予期しないエラーが発生しました。読み取りの場合は指数バックオフで再試行し、書き込みの場合はまずレコードを再度読み取ってください（書き込みの再試行には注意が必要を参照）。サポートに問い合わせる場合は、correlation_idを記載してください。

dependency_unavailable

503: APIが依存するサービスが一時的に利用できません。バックオフを使用して再試行してください。

429については、上記のrate_limitedを参照してください。

コードでのエラー処理

まず HTTP ステータスを確認し、書き込みの場合は、レスポンスボディ内にネストされた errors 配列がないかを調べます。

from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try:    location = client.locations.create(input=payload)except APIError as e:    # Raised for a non-2xx status (AuthenticationError, ValidationError, and    # so on) and for an error payload returned inside a 200 body.    raise RuntimeError(f"Listings API error: {e}") from e

HTTP API を直接使用する場合も、ステータスコード、次にレスポンスのペイロードという同じ 2 つの確認を明示的に行います。

resp = requests.post(    "https://listingsapi.com/api/v4/locations",    headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"},    json=payload,    timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"):    messages = [e["message"] for e in op["errors"]]    raise RuntimeError(f"Listings API error: {messages}")

Python SDK は、この両方を処理します。各 HTTP ステータスを型付きの例外にマッピングし、200 ボディ内で返されるエラーペイロードに対しても例外を発生させます。