Codexに外部API連携を任せる前に決めること

3行まとめ

Timeout

待ち時間。

Retry

再試行。

Quota

上限。

Mock

代替。

外部API連携は、接続できた時より失敗した時の仕様で品質が決まります。

• Codexに外部API連携を任せる時は、endpointと認証情報だけ渡すのではなく、timeout、retry、quota、rate limit、mock、失敗時の見せ方まで先に決めます。
• API keyはAIへ見せる材料ではなく、実行環境へ注入する権限です。scope、保存場所、ログへの出方、rotationを分けます。
• 本番APIへつないでから直すのではなく、mock、contract test、sandbox、dry-runで分岐を先に確認し、429、5xx、timeout、partial successを完了条件に入れます。

Codexに「この外部APIをつないで」と頼むと、見た目には早く進みます。SDKを入れ、clientを作り、buttonやjobから呼び出し、responseを画面へ出す。小さなdemoならそれで動きます。

ただ、外部API連携で本当に壊れるのは、接続できない時です。APIが遅い。429で止まる。5xxが返る。認証tokenが切れる。retryが重複POSTになる。テストが本番APIへ当たる。ログにsecretが出る。ここを曖昧にしたままAIに任せると、動いた差分なのに運用では怖い差分になります。

この記事では、Codexに外部API連携の実装を頼む前に、依頼文へ入れるべき条件を整理します。ネットワーク許可そのものは公開済みのCodexにインターネットアクセスを許可する前にで扱いました。ここでは、許可した後にどんな実装仕様で渡すかに絞ります。

この記事でわかること

Auth

認証。

Limit

制限。

Test

確認。

Fallback

退避。

実装依頼に入れる項目を先に決めると、差分レビューが短くなります。

• 外部API連携をCodexへ頼む前に決める6項目
• timeoutとretryを「実装者の好み」にしない書き方
• quota、rate limit、429 responseを仕様へ入れる理由
• API keyやOAuth tokenをAIへ見せずに実装する考え方
• mock、contract test、sandboxを使った確認順序
• 失敗時にユーザーへ何を返すかを先に決める方法
• Codexへそのまま渡せる依頼packet
• reviewで見るべき差分と、止めたほうがよい実装

この記事は、特定APIの攻略手順ではありません。決済、メール配信、GitHub連携、CRM、LLM API、地図、翻訳、社内APIなど、外部サービスへ接続する実装で共通する整理です。実際の制限値、禁止事項、料金、rate limit、認証方式は、導入するAPIの公式Docsで確認してください。

前提知識

項目	内容	見方
Codex		権限。
Best practice		本番。
Rate limit		上限。
Idempotency		重複。
Abort		中断。

外部API連携では、AIツールの権限とAPI側の制限を両方見ます。

Codexへ外部API連携を任せる時、2種類の境界があります。

1つ目は、Codexが作業中に外部通信してよいかという境界です。OpenAIのCodex Securityでは、sandbox、approval、network accessのような安全境界を踏まえて使う考え方が説明されています。実装中にpackageを取るのか、API Docsを調べるのか、sandbox APIへ接続するのかは分けて扱います。

2つ目は、作るアプリケーションが本番で外部APIへ接続する境界です。こちらは、timeout、retry、認証、rate limit、idempotency、ログ、監視、fallbackの話です。Codexの作業権限を絞っていても、生成されたコードが本番で危ない呼び方をしていれば意味がありません。

AIに任せる範囲を先に切る

Codexに任せるのは、clientの作成、型定義、error mapping、mock、test、呼び出し箇所の接続、docs更新などです。一方で、API keyの発行、本番権限の付与、課金上限の変更、外部サービスへの本番POSTは、人間の承認と運用手順に残します。

live API前提でテストを書かない

外部API連携のテストを、最初からlive API前提にすると壊れやすくなります。ネットワーク、quota、sandbox状態、外部障害、認証情報の期限に左右されます。まずmockで分岐を確認し、contract testでresponse shapeを固定し、必要なところだけsandboxやstagingで確認します。

外部API連携で先に決める6項目

項目	内容	見方
Purpose		目的。
Auth		認証。
Timeout		時間。
Retry		再試行。
Quota		上限。
Mock		代替。

最初に決める項目が少ないほど、実装中に判断が漏れます。

Codexへ頼む前に、最低でも6項目を決めます。

項目	決めること	曖昧なまま起きること
目的	何を達成するAPI連携か	不要なendpointまで実装される
認証	API key、OAuth、署名、scope	secret露出や権限過多になる
timeout	何秒待つか、どこで中断するか	requestが詰まり続ける
retry	何を何回再試行するか	重複POSTやAPI乱打になる
quota	rate limit、料金上限、日次上限	429や課金事故に気づけない
test	mock、contract、sandbox、本番確認	テストが外部状態に依存する

この6項目がない依頼は、「APIをつなぐ」ではなく「たぶん動く接続を作る」依頼になりやすいです。Codexは実装を進められますが、運用上の判断までは勝手に決めさせないほうが安全です。

目的を狭くする

最初に、API連携の目的を1文にします。

たとえば「購入後に領収書PDFを取得する」「Issue番号からtitleとstateだけ読む」「配送statusを1時間ごとに同期する」のように、読み取り、書き込み、同期、通知を分けます。

「CRM連携を作る」では広すぎます。顧客作成、タグ更新、note取得、email送信、webhook受信は、それぞれ副作用と失敗時の扱いが違います。

endpointを絞る

Codexへ渡すendpointは、必要なものだけにします。API Docs全体を渡して「よしなに」ではなく、使ってよいendpoint、method、request field、response fieldを指定します。

reviewで見ること

差分reviewでは、指定していないendpoint、広すぎるSDK helper、write権限のあるmethod、不要なfield取得が増えていないかを見ます。

timeoutとretryを仕様にする

1. 1Timeout

   待つ。

2. 2Classify

   分類。

3. 3Retry

   試す。

4. 4Stop

   止める。

retryはやさしさではなく、条件付きの処理です。

timeoutは、外部APIが遅い時にどこで諦めるかです。retryは、一時的な失敗にもう一度だけ期待する処理です。この2つを、実装者の好みにしないでください。

Codexへ依頼する時は、次のように書きます。

API requestは3秒でtimeoutする。
GETはtimeoutまたは5xxに限り最大2回retryする。
POSTはidempotency keyがある時だけretryする。
429はRetry-Afterまたはreset時刻を見てbackoffし、即時連打しない。
4xxはretryせず、ユーザーへ修正可能なerrorとして返す。

この程度の条件があるだけで、生成されるコードの質が変わります。

retryしてよい失敗

retryしてよいのは、同じrequestをもう一度送っても意味があり、外部APIにもユーザーにも迷惑が少ない失敗です。典型的には、一部のtimeout、接続断、一時的な5xxです。

ただし、POSTや決済やメール送信のような副作用がある処理は別です。重複作成や二重送信が起きるため、idempotency keyや重複検知がない限り、安易にretryしません。

retryしない失敗

認証失敗、permission不足、validation error、存在しないresource、料金未払い、scope不足は、retryしても直りません。これらはユーザーや運用者へ返すerrorです。

実装で見ること

catchで全errorをまとめてretryする実装は止めます。error class、status code、response header、operation typeを見て、retry可否を分けます。

quotaとrate limitを作業条件に入れる

項目	内容	見方
Window		期間。
Remaining		残量。
Reset		回復。
Backoff		待機。

rate limitを仕様へ入れると、動くけれど迷惑な実装を避けられます。

外部APIには、rate limit、quota、課金上限、同時実行数、payload size、pagination制限があります。Codexへ渡す依頼にこれを入れないと、機能としては動くが運用では荒い実装になります。

GitHub REST APIのDocsではrate limitの考え方やheaderが説明されています。Stripe Docsではidempotent requestの扱いが説明されています。どのAPIでも同じ値ではありませんが、「API側には上限と重複対策がある」という前提を持つことが大事です。

429を成功でも失敗でもない状態として扱う

429は「実装が壊れた」というより、「今は待つべき」という状態です。すぐにerror画面へ落とすのか、jobを遅延させるのか、ユーザーに再試行を促すのかを決めます。

batch処理なら、429で全体を失敗にするより、対象をdeferred queueへ戻すほうがよいことがあります。画面操作なら、短い説明と再試行可能なUIを出すほうが自然です。

usageをログへ残す

API response headerに残量やreset時刻がある場合は、debug logやmetricsへ入れます。ただし、headerやpayloadにsecretや個人情報が混ざる場合はmaskします。

条件

Codexへは、rate limitを無視してparallel化しないこと、paginationで全件取得しないこと、429やquota不足をretry stormにしないことを明記します。

authとsecretを分ける

Scope

権限。

Env

注入。

Mask

伏せる。

Rotate

交換。

API keyは実装材料ではなく、実行環境が持つ権限です。

API keyやOAuth tokenは、Codexへ貼るものではありません。実装では、環境変数、secret manager、CI secret、runtime configから読みます。Codexに必要なのは、secretの値ではなく、どの名前で、どのscopeで、どこから注入されるかです。

実装では EXTERNAL_API_TOKEN を参照する。
値は渡さない。
tokenのscopeはread:invoiceのみ。
ログ、error、test snapshotへtokenを出さない。
認証失敗時は再認証が必要な状態として扱う。

このように書けば、Codexはsecret値なしで実装できます。

scopeを小さくする

最初はread-onlyや限定scopeから始めます。writeが必要なら、対象resourceとmethodを絞ります。すべての管理APIを触れるtokenを渡すと、実装ミスの被害が大きくなります。

secretをログに出さない

API clientのdebug log、HTTP error、test snapshot、PR comment、browser traceにsecretが出ることがあります。Codexへは、request headerやauthorization値をそのまま出力しないことを条件にします。

reviewで見ること

console.log(process.env...)、error objectの丸ごと出力、request configのsnapshot保存、CI logへのheader出力がないかを見ます。

mockとcontract testを先に作る

1. 1Schema

   形。

2. 2Mock

   代替。

3. 3Contract

   契約。

4. 4Sandbox

   確認。

本番APIへつながなくても、ほとんどの分岐は先に確認できます。

外部API連携では、mockを手抜きと考えないほうがいいです。mockは、外部依存を切り離して分岐を確認するための道具です。

Codexへは、最初にresponse shapeとerror caseを固定させます。

成功response、404、429、5xx、timeoutのfixtureを作る。
API clientはfixtureを使ったunit testで分岐を確認する。
contract testはsandboxで1 endpointだけ確認する。
本番APIへ接続するtestは通常CIでは走らせない。

mockで確認すること

mockでは、正常系だけでなく失敗を確認します。timeout、429、認証失敗、validation error、空配列、pagination、partial success、予期しないfield追加を入れます。

contract testで確認すること

contract testでは、外部APIの実際のresponse shapeが、自分たちの型や変換処理とズレていないかを見ます。全部の分岐をlive APIで試す必要はありません。代表endpointを少数に絞り、実行条件を明記します。

注意点

mockが強すぎると、実APIと違う世界をテストするだけになります。公式Docs、sandbox response、録画済みfixtureをもとに更新し、更新履歴を残します。

失敗時の動きを決める

項目	内容	見方
Timeout		保留。
429		待機。
5xx		再試行。
4xx		修正。
Partial		補償。

外部APIの失敗は、例外処理ではなくプロダクト仕様です。

外部APIの失敗は、例外処理ではなくプロダクト仕様です。

失敗	ユーザー向け	運用向け
timeout	少し待って再試行できる説明	endpoint、duration、attempt
429	時間を置く説明	remaining、reset、queue状態
401/403	連携設定の確認を促す	scope、token名、tenant
404	対象が見つからない説明	resource id、同期状態
5xx	一時的な障害として扱う	retry回数、外部status
partial success	成功分と失敗分を分ける	item id、補償処理

Codexは、例外を握りつぶして「失敗しました」とだけ返す実装を作ることがあります。これは画面上は簡単ですが、運用では原因が追えません。逆に、外部APIの生errorをそのまま見せると、内部情報やsecretが出ることがあります。

user messageとlogを分ける

ユーザー向けmessageは短く、次の行動が分かるものにします。運用logには、correlation id、operation、status、attempt、duration、rate limit情報を残します。payload全体や認証headerは残しません。

partial successを決める

batchや同期処理では、一部だけ成功することがあります。全部rollbackするのか、成功分を残すのか、失敗分だけretryするのかを決めます。Codexへ依頼する時点でここが未定だと、実装中に都合のよい処理が入ります。

評価基準

失敗時に、ユーザーが次に何をすればよいか、運用者が何を見ればよいか、外部APIへ再実行して安全かを説明できるなら、連携仕様としてかなり健全です。

Codexへ渡す依頼packet

項目	内容	見方
Goal		目的。
Allowed		許可。
Forbidden		禁止。
Tests		確認。
Review		観点。

packetにすると、Codexの判断と人間のレビューを同じ表で見られます。

以下のようなpacketにして渡すと、Codexの実装と人間のreviewが揃います。

目的:
  請求書IDからPDF URLを取得し、画面にdownload linkを表示する。

使ってよいAPI:
  GET /v1/invoices/{id}
  GET /v1/invoices/{id}/pdf

禁止:
  invoice作成、顧客更新、本番POST、全件同期、secret値の出力。

認証:
  EXTERNAL_API_TOKEN を環境変数から読む。値はpromptへ貼らない。
  scopeは invoice:read のみ。

timeout/retry:
  request timeoutは3秒。
  GETのみ最大2回retry。
  429はRetry-Afterまたはreset時刻を見て待つ。
  4xxはretryしない。

test:
  success、404、429、5xx、timeoutのfixtureを作る。
  unit testはmockで実行する。
  sandbox contract testは手動commandに分ける。

review:
  secretがlogやsnapshotへ出ないこと。
  指定外endpointを使っていないこと。
  user messageとoperation logを分けること。

このpacketは長く見えますが、実装後の手戻りをかなり減らします。Codexに自由に設計させる部分と、人間が決める部分が分かれるからです。

依頼文に入れると効く一文

「不明な制限値は仮置きせず、TODOまたは設定値にして、公式Docsで確認が必要な項目として残してください。」

この一文は有効です。AIは自然な値を埋めたくなります。timeout 30秒、retry 3回、batch 100件など、もっともらしい数字が出ることがあります。数字はAPIやプロダクトで意味が変わるので、根拠がなければ仮置きとして明示させます。

よくある失敗

No timeout

待ち続ける。

Blind retry

乱打。

Raw secret

露出。

Live test

本番依存。

API連携の事故は、接続成功の裏側にある未定義から起きます。

API Docs全体を貼って丸投げする

Docs全体を渡すと、Codexは便利なhelperや広いscopeを選ぶことがあります。使ってよいendpointとfieldを絞ります。

本番tokenで動作確認する

本番tokenは最後です。先にmock、sandbox、read-only tokenで確認します。本番でしか分からないものがある場合も、実行者、時刻、対象、rollbackを決めます。

retryを増やせば安定すると思う

retryは安定化ではなく、外部APIへ追加の負荷をかける処理です。429や5xxに対して雑にretryすると、障害時にさらに悪化します。

test snapshotへresponseを丸ごと残す

responseには、個人情報、内部ID、署名付きURL、token、契約情報が混ざることがあります。snapshotは便利ですが、保存してよいfieldだけに削ります。

成功responseだけで実装を終える

成功だけならdemoはできます。実運用で必要なのは、遅い、失敗する、制限される、重複する、途中で止まる時の扱いです。

FAQ

項目	内容	見方
Retry?		条件。
Mock?		先に。
Secret?		見せない。
Release?		段階。

迷ったら、再実行しても安全か、外部へ迷惑をかけないかを見ます。

retry回数は何回がよいですか

固定の正解はありません。APIの公式Docs、処理の副作用、ユーザー体験、rate limitで決めます。重要なのは、retry条件、最大回数、待機方法、止める条件を仕様として残すことです。

mockだけで十分ですか

十分ではありません。mockは分岐の確認に強いですが、実APIのshape、認証、rate limit header、sandbox特有の挙動は別に確認します。mock、contract、sandboxを役割分担します。

API keyをCodexに貼らないと実装できませんか

多くの場合は不要です。環境変数名、scope、読み取り方、想定error、test fixtureがあれば実装できます。実際の値はCI secretやsecret managerへ置きます。

MCP toolとして社内APIを渡す場合も同じですか

基本は同じです。MCPの場合は、さらにtool単位の権限、read/write分離、承認、audit logが必要です。外部API clientを作るより、AIが直接実行できる入口になるぶん慎重に扱います。

Codexにどこまで直させてよいですか

client、型、mock、error mapping、test、docs更新までは任せやすいです。API key発行、scope変更、本番実行、課金上限変更、外部サービスの設定変更は、人間承認に残します。

次に読むなら

参照した主な情報源

• OpenAI Developers: Codex Security
• OpenAI API platform: Production best practices
• GitHub Docs: Rate limits for the REST API
• Stripe Docs: Idempotent requests
• MDN Web Docs: AbortController

更新履歴

1. 2026.06.01

   初版。

API制限やSDKは変わるため、導入時に公式Docsを確認します。

• 2026.06.01: 初版公開。Codexへ外部API連携を任せる前のtimeout、retry、quota、auth、mock、失敗時の扱いを整理しました。