うまくいかないとき
勘ではなく、エンジニアのように API エラーを診断する
⏱ 想定 ~6 分
01 · 読む
API は壊れます。サーバーは落ちます。キーは期限切れになります。レート制限に当たります。 URL はタイプミスします。
初心者とエンジニアの違いは、トラブルが起きるかどうかではなく —— どれだけ速く診断して直せるかです。
体系的なアプローチ:
1. ステータスコードを読む —— エラーのカテゴリは? 2. レスポンス本文を読む —— 何がいけないかサーバーが明示しているはず 3. ヘッダーを見る —— Retry-After 、 WWW-Authenticate 、 X-RateLimit-* は宝の山 4. URL を確認する —— タイプミス 1 つで全部壊れます
ポイントまとめ
- デバッグでは必ず curl -i —— ヘッダーが見える必要があります
- エラー本文はステータスコードよりも役立つことが多いです
- 4xx = あなたの問題。 5xx = 向こうの問題。
- 手詰まりになったら、 API プロバイダのステータスページを見ましょう
02 · コード例
ステータスコードのカテゴリ別の診断チェックリストです。
4xx —— クライアントエラー (あなたが間違っている)
400 Bad Request
→ Check: Is your JSON valid? Are required fields present?
→ Fix: Validate your -d body. Check the API docs for required fields.
401 Unauthorized
→ Check: Did you include the Authorization header? Is the key correct?
→ Fix: Check your API key. Make sure you're using the right header format.
403 Forbidden
→ Check: Do you have permission? Is this feature on your plan?
→ Fix: Check your account permissions or upgrade your plan.
404 Not Found
→ Check: Does the URL path exist? Did you replace all {placeholders}?
→ Fix: Double-check the URL against the docs. Check the resource ID.
429 Too Many Requests
→ Check: Look for Retry-After header — it tells you when to retry.
→ Fix: Slow down. Implement exponential backoff. Use caching.
5xx —— サーバーエラー (向こうの問題)
500 Internal Server Error
→ Their code crashed. Check their status page.
→ Retry after a brief wait.
503 Service Unavailable
→ Server is overloaded or in maintenance.
→ Check their status page. Wait and retry.
504 Gateway Timeout
→ Your request took too long. The server gave up.
→ Try again. If persistent, contact the API provider.
curl のエラー (レスポンスすら受け取れていない)
curl: (6) Could not resolve host
→ DNS failure. Check the hostname for typos.
→ Verify your internet connection.
curl: (7) Failed to connect
→ Server unreachable or port blocked.
→ Check if the service is down.
curl: (35) SSL certificate problem
→ Certificate expired or invalid.
→ Check if you're using https:// correctly.
03 · 実機演習
存在しない GitHub リポジトリにリクエストして、本物の 404 を引き起こします。
curl -i https://api.github.com/repos/this-user-doesnt-exist-xyz/no-such-repo
04 · 実機演習
認証が必要なエンドポイントに認証なしでリクエストを送り、本物の 401 を引き起こします。
curl -i https://api.github.com/user
05 · クイズ
API を呼んだら 429 ステータスコードが返ってきました。何をすべきですか?
- API キーを確認する
- URL を変更する
- POST リクエストに切り替える
- 少し待ってからリトライする —— レート制限に当たっている
06 · 空欄補充
4 で始まるステータスコードは、エラーが _____ 側にある (あなたのリクエストが間違っている) ことを示します。
⚠ 全機能のインタラクティブ体験には JavaScript が必要です。JavaScript を有効にして再読み込みしてください。
※ このサイトは独立した教育プロジェクトで、Anthropic の公式製品ではありません。Claude™ は Anthropic, PBC の商標です。