エラーと再試行

APIの失敗はHTTPステータスとJSON本文で返します。

{
  "message": "フィードバックが見つかりません。",
  "statusCode": 404
}

この例はAccept-Language: jaを使います。messageは表示用で言語によって変わります。入力エラーにはtitle: ...; issueIds: ...のようなフィールドパスを含む場合があります。REST APIは別の固定文字列エラーコードを提供しません。

HTTPステータス別の処理

状態	主な原因	対処
400	UUID、フィールド、query、PR URLが不正。別アプリの報告	入力を修正
401	セッションなし、トークン期限切れ・取り消し・不正、トークン管理にBearer使用	認証を確認
403	所有者ではない、別アプリのトークン、権限不足、Origin不許可	アプリ・権限・送信元を確認
404	対象アプリに報告・作業・トークンがない	IDとアプリを再確認
409	同じIDで異なる内容、または別のPRが関連付け済み	既存作業を確認
413	JSON本文が64 KiB超	本文を縮小
429	リクエスト過多	Retry-After秒待つ
500	サーバー処理失敗	回数を制限して時間を空けて再試行

最初に失敗した検査の結果が返ります。例えばOriginなしの不正Bearer変更リクエストは、トークン検査前に403になる場合があります。

レート制限

既定のAutomation API制限はIPごとに毎分120回で、フィードバック、修正作業、トークン管理で共有します。アプリやトークンを替えても同じIPの利用量に合算されます。デプロイやプロキシ設定により追加制限がある場合があります。

429応答は待ち時間を秒で返します。

HTTP/1.1 429 Too Many Requests
Retry-After: 28
Content-Type: application/json

ポーリングには間隔を設け、必要なページだけ取得します。同じリクエストを短い間隔で繰り返さないでください。

応答を受け取れない場合

通信断やクライアントのタイムアウトでも、サーバーでは処理が完了している可能性があります。

操作	再試行の規則
報告・作業・トークン取得	同じリクエストで再試行
修正作業作成	同じclientRequestIdと本文を保持
PR関連付け	同じ作業IDとPR URLを保持
トークン取り消し	同じトークンIDで再試行
トークン発行	自動再試行しない。毎回別トークンが発行される

作成にはJSONのclientRequestIdを使い、Idempotency-Keyヘッダーはありません。同じアプリ・作成者・キーで異なる内容は409です。結果が確定するまでIDと本文を一緒に保持します。

429ではRetry-Afterを優先します。一時的な通信・サーバーエラーには、回数を制限した指数バックオフとランダムな待機を使います。400、401、403、404、409は原因を解決してから再試行します。

よくある問題

同じ所有者の別アプリで403

トークンは1つのアプリに限定されます。対象アプリ用に発行し、OPENTESTER_APP_IDを一致させます。

書き込みできるが読み取りに失敗する

権限は独立しています。報告取得にはfeedback:read、作業取得にはwork-items:readが必要です。

文書ドメインからのリクエストが失敗する

文書サイトは静的です。自動化にはAPI基本URLを使い、トークン管理などのWebセッション要求はログイン済みコンソールのOriginから行います。認証を参照してください。

PR関連付け後も報告がopenのまま

正常です。PR関連付けは作業にURLを保存します。報告の確認と状態変更はコンソールで別途行います。