API が急に 401 になった — 期限・鍵の再発行・そもそも入れない
昨日まで動いていた連携が 401 を返すようになった。401 は「あなたが誰か分からない」という返事で、原因は 3 つに分かれます。
3 つの原因と、切り分け方
| 原因 | 起きていること | 見分け方 |
|---|---|---|
| 期限 | アクセストークンの期限が切れ、更新の仕組みが止まっている | その連携だけが止まっている。再認証すると直る |
| 鍵の再発行 | API キーを誰かが再発行した | 同じ鍵を使っている連携が全部同時に止まる |
| そもそも入れない | 契約の段が変わった・審査が要る・プランで API が閉じた | 再認証しても直らない。契約と申請の欄を読む |
切り分けで一番速いのは 2 行目です。他の連携も同時に止まったかどうかを聞けば、鍵の再発行かどうかが分かります。
期限は「短いのが普通」
アクセストークンの期限は短いのが普通です。調査記録でも、Zoho CRM は「各アクセストークンは 1 時間だけ有効」、BowNow は「アクセストークンの有効期限は 6 時間」で、どちらも更新の仕組み（リフレッシュトークン）と組み合わせて使う設計です。
| 型 | 切れ方 | 直し方 |
|---|---|---|
| OAuth（更新あり） | 更新の仕組みが動いていれば切れない。止まると 401 | 更新が失敗している理由を見る（取り消された・範囲が変わった） |
| OAuth（更新なし・再認可が要る） | 期限で切れる | 人が許可し直す。その予定を運用に入れる |
| API キー | 期限は基本的にない | 切れたのではなく、替わったか外された |
範囲と期限を決めて渡せるのは OAuth の側の性質です。
401 と 403 と 429 を混ぜない
| 返り | 意味 | 直す方向 |
|---|---|---|
| 401 | 誰か分からない | 認証をやり直す・鍵を確かめる |
| 403 | 誰かは分かるが、許されていない | 範囲（scope）と契約の段・申請を確かめる |
| 429 | 回数が多すぎる | 呼び出し回数の上限の設計を直す |
3 つを混ぜると、認証を直しても止まったままになります。エラーコードを記録に残しておくと、この切り分けが後からできます。
こう直す — 手順
| 順 | 手順 | こう判定する |
|---|---|---|
| 1 | 他の連携も同時に止まったかを聞く | 全部止まっていれば鍵の再発行。1 つだけなら期限か設定 |
| 2 | 認証方式を確かめる（調査記録の認証の欄） | OAuth なら更新の仕組み、API キーなら発行の履歴を見る |
| 3 | 再認証してみる | 直れば期限。直らなければ 3 つ目の原因（契約・審査・プラン） |
| 4 | 契約と申請の欄を読む | 上位プラン限定・申込制・NDA が条件のシステムがある |
| 5 | 鍵の持ち主と本数を決め直す | 1 本を複数の連携で使い回していたなら、分けられるかを確かめる |
止まった原因が相手側かどうかの切り分けは 相手が落ちているのか、自分だけか に置きました。