「GHLのAPIが落ちた」の最頻原因は403。User-Agentを付けて確かめる

Claude Codeに、GoHighLevelのAPIを叩くスクリプトを書かせる。最初の1本が動かず、403が返る。私たちが何度も見た光景です。

この記事では、その403の最も多い原因と、見分け方をお伝えします。「APIが落ちた」と判断して時間を使う前に、確認してほしい点です。

症状は、鍵が正しいのに403が返ること

トークンは正しく、権限も足りているはずなのに、403が返ります。応答の中身を見ると、GoHighLevelのエラーではなく、Cloudflareの画面が返っています。エラー番号は1010、意味は browser_signature_banned です。

ここで「GoHighLevelが落ちた」「トークンが無効になった」と考えると、遠回りになります。私たちの手引きでは、「APIが落ちた」という誤診の入口として、最も多いものに挙げています。

原因は、User-Agentが無いこと

GoHighLevelのAPIの前には、Cloudflareがいます。Cloudflareは、スクリプトの既定のUser-Agentを、ブラウザではないものとして弾きます。curlの既定やPythonの標準ライブラリの既定が、これに当たります。

直し方は、ブラウザの文字列をUser-Agentとして付けることです。それだけで、同じリクエストが200になります。リトライしても直りません。待っても同じ403が返るので、「一時的な障害かもしれない」と待ち続けないことです。

新しいスクリプトを書くたびに起きる

この403は、新しくスクリプトを書くたびに再発します。Claude Codeが、標準のHTTP通信で簡単な呼び出しを書くと、User-Agentが付いていないからです。

私たちは、2つの手を打ちました。1つは、GoHighLevelを呼ぶ共通の補助スクリプトを1本に決め、User-Agentをそこで付けること。もう1つは、新しい呼び出しを書かせるときの最初の指示に、「User-Agentにブラウザの文字列を付けること」を入れることです。

403の理由は2つある

話をややこしくするのは、403の理由が1つではないことです。私たちは、音声の応対の設定を読むときに、別の403にも当たりました。

• User-Agentが無い：Cloudflareの1010
• locationId が無い：GoHighLevel側の拒否

2つめは、クエリに locationId を付け忘れたときです。応答の形が違うので、見分けられます。1010はCloudflareの画面の形で、locationId の拒否は、JSONのエラーの形で返ります。

両方を付けて、ようやく200になります。403が返ったら、まず応答の形を見て、どちらの403かを判断します。

切り分けの順番

私たちは、403と401と404が出たとき、次の順で確かめています。

• 403で、応答がCloudflareの画面なら、User-Agentを付ける
• 403で、応答がJSONなら、locationId と、トークンの権限（スコープ）を見る
• 401は、そのトークンにその口のスコープが無いという意味。トークンの種類を見直す
• 404は、口が無いか、IDの種類が違う。コンタクトのIDとオポチュニティのIDの取り違えも、ここに含まれる

401と403を一緒にして「権限が足りない」と言うと、直す方向を誤ります。どの口で、どの形の応答が返ったかを、記録しておくのが近道です。

私たちの実測

この403は、自分の運用手引きに「誤診の最頻の入口」として書き残してあります。最初に実測したのは2026年8月27日で、素の通信で叩くと1010で弾かれ、ブラウザの文字列を付けると同じ呼び出しが200になることを確かめました。

それ以来、GoHighLevelを呼ぶ補助スクリプトはUser-Agentを自動で付ける作りにしてあります。素の通信で直接叩く新しいスクリプトを書くときだけ、付け忘れが起きます。

「APIが落ちた」と書く前に、User-Agentを1行足して、もう1回だけ叩く。この手順を障害対応の最初の1手に加えておくと、原因の切り分けに使う時間を減らせます。

Claude Codeへの指示に入れる3行

新しい呼び出しを書かせる最初の指示には、次の3行を入れています。

• 呼び出しは、共通の補助スクリプトを通す
• 自前で通信を書くときは、User-Agentにブラウザの文字列を付ける
• 403が返ったら、応答がCloudflareの画面かJSONかを、最初に記録する

この3行があると、403が出たときの最初の質問が決まります。原因の候補を広げる前に、応答の形という事実から始められます。

次に読む

403を抜けたら、次は一覧を最後まで読む段階です。ページの送り方で、黙って同じデータを返され続ける罠は、一覧の取得の記事にまとめました。