トラブルシューティング

API 利用中によく起きるエラーと対処法をまとめます。

401 Unauthorized

リクエストが認証層で拒否された状態。

原因	対処
access_token の TTL (10 時間) 超過	refresh_token で更新するか再度 authorize
revoke 済みのトークン	再度 authorize して新しいトークンを取得
`Authorization` ヘッダの形式不正	`Authorization: Bearer <access_token>` (先頭の `Bearer` 大文字、空白 1 つ)
対象 Application が DCR 経由で登録されていない	内部用 OAuth Application を流用していないか確認。必ず `/api/v1/oauth/register/` で発行したトークンを使う
ユーザーアカウントが無効化されている	別の有効なアカウントで authorize

認証は通ったが、操作する権限がない状態。

原因	対処
操作に必要な scope がトークンに含まれていない (例: オーダー作成に `orders:write` が無い、オーダー参照に `orders:read` が無い)	scope 一覧を確認し、DCR と authorize の両方で必要な scope を指定して再取得
`Current-Team` ヘッダで指定したチームのメンバーでない	`GET /api/v1/external/teams/` で利用可能なチーム一覧を取得し、有効な team_uuid を渡す
操作対象 (オーダー / コンタクト等) が別チームのリソース	チームスコープが一致しているか確認
IP whitelist に弾かれている	社内 IP 制限を設定している場合、許可リストを SendWOW 営業担当に確認

原因	対処
パス / メソッドが対応していない	API リファレンスで利用可能な操作を確認
対象リソース (オーダー UUID 等) が存在しない / 別チームのもの	`Current-Team` と ID の整合を確認
trailing slash の有無の違い	エンドポイントは末尾 slash 付きが基本 (`/api/v1/external/orders/`)

token 取得時に返るエラー。以下のいずれか:

特に PKCE は code_challenge_method=S256 固定で、verifier は authorize 時の challenge と同じ session 内で生成したものでなければなりません。

クライアント登録時の scope と authorize 要求 scope が不整合の場合に発生します。

状況	対処
DCR 時に登録していない scope を authorize で要求した (例: `orders:read` のみで登録したクライアントが `orders:write` を要求)	必要な scope を含めて再 DCR するか、authorize の `scope` を登録済みの範囲に絞る

DCR (/oauth/register/) で 400 が返るケース:

原因	対処
`redirect_uris` の scheme が未対応	`https://` + ホスト名で指定 (loopback の `http://` と `cursor://` 等の private-use scheme は可)
`redirect_uris` に空白 / 改行 / fragment が含まれる	URI を再確認
`client_name` に `<` / `>` / 制御文字 / 改行	プレーンな文字列で再
`scope` がサポート外 (`openid` 等のみ指定)	scope 一覧の値を 1 つ以上含める (未知の scope は無視されるが、全て未知だと 400)

POST /api/v1/oauth/register/ は同一 IP から 20 回 / 時 の制限があります。引っかかった場合は時間を置くか、運用上必要な場合は SendWOW 営業担当に事前ご相談ください。