APIエラー（401/403/429/500）の意味と、現場での対処方法

APIエラーは「相手先システムとのやり取りが止まったサイン」

社内システムやSaaS連携、チャットボット、RPA、データ連携基盤などでAPIを使っていると、突然「401」「403」「429」「500」といった数字が表示され、業務が止まることがあります。結論から言うと、これらは相手先（または自社）のサーバーが返す“状態コード”で、原因の当たりをつけるための重要な手掛かりです。

開発に詳しくない立場だと「とにかくエラー」とひとくくりにしがちですが、APIエラーは種類によって打ち手がまったく異なります。たとえば401/403は「権限・認証の問題」、429は「使いすぎ（アクセス集中や制限超過）」、500は「相手側の内部不具合（または自社の投げ方の問題）」といった具合です。まずは数字を見て、適切な担当者に適切な情報を渡せるかどうかで復旧速度が大きく変わります。

この記事では、現場でよく起きる4つのAPIエラー（401/403/429/500）を、非エンジニアでも判断できる言葉に翻訳し、切り分けと対処の優先順位、確認項目、再発防止までをまとめます。読み終えるころには、情シスや業務担当として「何を確認し、何を開発会社やベンダーに伝えるべきか」が整理できるはずです。

最初に押さえる：ステータスコードと“誰の問題か”を切り分ける

APIエラーの数字は、HTTPステータスコードと呼ばれる分類です。ざっくり言うと、400番台は「依頼の出し方・権限・条件が合っていない」ことが多く、500番台は「サーバー側で処理に失敗した」ことが多い、という目安になります。ただし実務では、500が返っていても原因が自社側（送信データの想定外など）にあるケースもあり、鵜呑みは禁物です。

現場対応で役立つのは、次の3点を最短でそろえることです。「いつ」「どの連携で」「どの条件で」失敗したかが分かるだけで、調査の半分が終わります。

• 再現条件：誰が・どの画面/バッチで・何をしたら起きたか（可能なら同じ操作で再現できるか）
• リクエスト識別：対象のAPI名、エンドポイントURL、時間帯、可能ならリクエストID/トレースID
• レスポンス情報：ステータスコード（401/403/429/500）、エラーメッセージ本文、レスポンスヘッダ（Rate limit情報など）

加えて、API連携の全体像（自社→中継サービス→相手先、など）を把握すると「どこで止まったか」を早く切れます。SaaS同士の連携（iPaaS）では、実際には複数のAPIが連鎖しているため、表に見えているエラーが“根本原因”ではないこともあります。連携ツールのログ画面や実行履歴から、どのステップで失敗したかを確認しましょう。

以降では、401/403/429/500ごとに「意味」「よくある業務シーン」「今すぐできる対処」「ベンダーに渡すべき情報」「再発防止」を順に解説します。

401 Unauthorized：認証できていない（鍵が違う・期限切れ）

401は一言でいうと「あなたが誰か分からないので処理できません」です。APIキー、アクセストークン、署名、Basic認証など、何らかの認証情報が不足しているか、間違っている、期限が切れているときに起きます。現場では「昨日まで動いていたのに急に止まった」という形で発生しやすく、トークンの有効期限や、認証方式の更新が原因になりがちです。

よくある業務シーンは次の通りです。

• 担当者がSaaSの連携設定を更新した（再ログイン・再接続が必要になった）
• APIキーを発行し直したが、連携側の設定に反映できていない
• アクセストークン（OAuth）が期限切れで、更新トークンの更新処理が失敗している
• 本番/検証環境を取り違えて別のキーを使っている

今すぐできる対処は、認証情報の棚卸しです。まず「どの方式で認証しているか（APIキーなのかOAuthなのか）」を確認し、次に「どこに設定されているか（連携ツール、サーバー環境変数、GitHub Actionsなど）」を特定します。iPaaSやSaaS連携機能の場合は、管理画面に「接続を更新」「再認証」といったボタンがあることが多いので、最初にそこを疑うと早いです。

開発会社やベンダーに依頼するときは、次の情報があるとスムーズです。「どの認証情報で、いつから、どの環境で」失敗しているかが要点です。

• 対象APIと環境（本番/検証）、失敗し始めた日時
• 認証方式（APIキー、OAuth、JWTなど）と、設定箇所
• 直近で実施した変更（キー再発行、連携設定変更、権限変更、IP制限設定など）
• レスポンスの本文（可能なら全文）

再発防止としては、鍵やトークンの運用ルールを作るのが効果的です。たとえば「キーの発行者・保管場所・更新手順」「担当者変更時の引き継ぎチェック」「期限があるトークンは期限前にアラート」といった管理を行うだけで、401の多くは減ります。クラウド環境なら、認証情報をソースコードに埋め込まず、秘密情報管理（Secret Manager等）で一元管理するのも定石です。

403 Forbidden：認証はできたが権限が足りない（許可されていない）

403は「あなたが誰かは分かったけれど、その操作は許可されていません」です。401との違いは、認証情報は正しい可能性が高い点です。権限（ロール）不足、契約プラン制限、アクセス元制限（IP制限・地域制限）、特定リソースへのアクセス禁止などが原因になります。実務では“設定変更”や“契約変更”の後に急に出るケースが目立ちます。

よくある原因を具体例で挙げます。

• SaaS側でユーザー権限（閲覧のみ等）になっており、更新系APIが拒否される
• 組織・プロジェクトが変わり、参照先のID（テナントID等）が別になっている
• API利用が上位プラン限定で、契約・アドオンが不足している
• セキュリティ設定でIP許可リストに自社サーバーが入っていない
• WAFやファイアウォールで特定パターンのリクエストが遮断されている

現場での対処としては、「誰の権限で呼んでいるか」を特定し、SaaS管理者に確認する流れが最短です。API連携は“サービスアカウント”で動いていることが多いため、実際に操作している担当者の権限を上げても直らない場合があります。連携設定画面に表示される接続ユーザー（接続先アカウント）や、APIキーの発行元ユーザーを確認しましょう。

また、403の切り分けでは、同じAPIでも「読み取りは通るが書き込みが拒否される」などの差が重要です。たとえばGETは成功するのにPOST/PUTだけ403なら、権限やスコープ（OAuthの許可範囲）が不足している可能性が高いです。成功する操作と失敗する操作の差分をメモして渡すと、調査が一気に早まります。

ベンダーに渡すべき情報は次の通りです。

• どの操作（参照/登録/更新/削除）で403になるか
• 呼び出しに使っているアカウント種別（人のアカウントか、サービスアカウントか）
• 直近の変更（権限変更、組織移行、IP制限、WAF設定、契約プラン変更）
• 相手先の管理画面で確認できる権限設定のスクリーンショット（可能な範囲）

再発防止は「権限の見える化」と「変更管理」です。API連携のサービスアカウントは、権限を強くしすぎるとリスクが上がりますが、弱すぎると業務が止まります。必要最小限の権限を明確にし、権限・IP制限・WAF・契約の変更時には“連携への影響確認”をチェックリスト化すると、403トラブルが減ります。

429 Too Many Requests：使いすぎ・急増（レート制限）

429は「短時間にリクエストが多すぎます。少し待ってから来てください」です。APIには多くの場合、レート制限（一定時間あたりの呼び出し回数制限）があります。業務が拡大してデータ件数が増えたり、バッチの頻度を上げたり、障害時にリトライが暴走すると、突然429が出るようになります。“正常に動いているが、量が増えて耐えられなくなった”サインとして捉えると分かりやすいです。

現場でよくある発生パターンは次の通りです。

• 月末の請求・集計で一気にデータ取得し、制限に達する
• 夜間バッチが複数同時実行され、呼び出しが集中する
• エラー時の自動リトライが短い間隔で連打してしまう
• ページングせずに大量取得を繰り返し、無駄な呼び出しが増える

今すぐの対処は「落ち着いて待つ」だけでなく、再実行の仕方を変えることです。まず、レスポンスヘッダやメッセージに「何秒待て」といった情報（Retry-Afterなど）が含まれる場合があるので確認します。次に、手動で再実行する場合も、連打は避け、時間を置いて行います。連携ツール側に「リトライ間隔」「最大リトライ回数」「指数バックオフ（徐々に待ち時間を増やす）」の設定があれば、即時に調整可能です。

恒久対策としては、設計の見直しが効きます。たとえば、データ取得は「差分取得」に変更する、更新系はまとめて送れるAPI（バルク）を使う、ジョブを分散させる、キャッシュを使う、同じ情報を何度も取りに行かない、といった改善です。429は“設計と運用の両方”で減らせるため、原因の見える化が重要です。

ベンダーに相談する際にあるとよい情報は以下です。

• 発生頻度（常時か、特定の時間帯だけか）と、ピーク時の呼び出し回数
• 対象APIと処理内容（一覧取得なのか、1件ずつ更新なのか）
• リトライ設定（間隔、回数、同時実行数）
• 相手先のレート制限仕様（契約プランによる違いも含む）

また、運用面では監視が有効です。429が出た回数、ジョブの処理時間、同時実行数を記録しておくと、「データ量が増えたのが原因」「リトライが暴走したのが原因」といった判断ができます。情シスとしては、月末・繁忙期の処理を前提に、余裕を持った設計と契約（上位プラン・追加枠）を検討するのが現実的な落としどころです。

500 Internal Server Error：相手先（または自社）の内部処理が落ちた

500は「サーバー内部で想定外のエラーが起きました」です。多くの人が「相手側の障害」と捉えますが、実務では「自社が送った内容が想定外で、相手側がうまく処理できず500を返した」というケースもあります。つまり、500は“相手が悪い”と決めつけず、送信データとタイミングを含めて切り分けるのが重要です。

500が起きやすいシーンは次の通りです。

• 相手先サービスの障害・メンテナンス・一時的な負荷増大
• 必須項目が欠けている、文字数超過、形式不正などの入力不備
• 特定データ（特殊文字、絵文字、改行コード、想定外のNULL）で処理が落ちる
• タイムアウト（相手側の処理が重く、途中で落ちる）

今すぐの対処は、(1)相手先の稼働状況確認、(2)リトライ、(3)データ差し替え・分割の順が基本です。まず相手先のステータスページや障害情報、メンテ情報を確認します。障害中なら、こちらでできることは限定されるため、業務側の代替（手入力、翌朝再実行、処理の一時停止）を判断します。障害情報がない場合は、短い間隔で連打せず、間隔を置いたリトライを行います。

同じデータで何度も500になる場合は、送信内容が引き金の可能性があります。たとえば「特定の顧客名に含まれる記号で落ちる」「備考欄が長すぎる」「日時形式がずれている」などです。可能なら、問題のデータを小さくして試し、どの項目が原因かを絞り込みます。バルク送信で500が出る場合は、データを分割して“どのレコードが毒”かを特定するのが有効です。エラーを起こす1件を特定できると、復旧も恒久対策も一気に進みます。

ベンダーや開発会社に渡す情報として、500は特に「ログ」が重要です。可能な範囲で次を用意しましょう。

• 発生時刻、対象API、相手先のリクエストID/トレースID（返ってくる場合）
• 送信したデータのサンプル（個人情報はマスキング）
• 発生条件（特定のレコードだけか、全件か、時間帯依存か）
• タイムアウトやネットワーク状況（社内回線変更、プロキシ変更など）

再発防止としては、入力バリデーション（送信前の形式チェック）、タイムアウトとリトライの適正化、サーキットブレーカー（失敗が続いたら一時停止）などが有効です。相手先に原因がある場合でも、こちら側で“失敗しても業務が止まりにくい”設計（キューイング、後で再送、手作業に切り替える手順）を用意しておくと、現場の混乱が減ります。

現場で迷わないための「一次対応チェックリスト」と、伝えるべきテンプレ

エラーが出た瞬間にやることを、情シス・業務担当向けにチェックリスト化します。ポイントは「復旧を急ぐ動き」と「原因調査に必要な証拠集め」を同時に進めることです。

次に、社内の開発担当や外部ベンダーへ連絡する際のテンプレです。文章が短くても、要点がそろっていると対応が早まります。

このテンプレを使うと、非エンジニアでも「情報が足りずに往復が増える」問題を回避できます。特に401/403は認証・権限の情報、429は呼び出し量と時間帯、500はリクエストIDとデータサンプルが重要です。

まとめ

APIエラーの401/403/429/500は、単なる数字ではなく「どこから手を付けるべきか」を教えてくれるヒントです。401は認証、403は権限、429は呼び出し過多、500は内部処理失敗（相手側障害も自社データ起因もあり）という整理だけでも、初動が変わります。

• 401：キー・トークンの期限切れや設定漏れ。再認証と秘密情報の管理が鍵。
• 403：権限・スコープ・IP制限・契約制限。サービスアカウントの権限を確認。
• 429：レート制限超過。リトライ設定の見直し、差分取得、分散実行で解決へ。
• 500：相手先障害か、送信データの想定外。ログとデータ分割で切り分ける。

現場では「影響の把握」「エラー情報の保存」「再現条件の整理」「暫定回避」を同時に進め、テンプレに沿って関係者へ連絡すると、復旧が早くなります。API連携は一度作って終わりではなく、データ量や運用が変わるほどトラブルが起きやすくなります。定期的に認証・権限・呼び出し量・監視を見直し、“止まらない仕組み”に育てていくことが重要です。