トラブルシューティング

このページでは、todoke を利用する際によく遭遇する 5 つの症状について、原因候補・確認方法・対処法をまとめています。エラーコードそのものの意味を調べたい場合はエラーコード・制限値を参照してください。

1. 通知が届かない

症状: POST /api/v1/notify などの送信 API・CLI・SDK の呼び出しは成功（またはエラーにならない）のに、ブラウザに通知が表示されない。

原因候補	確認方法	対処
対象の購読が非アクティブ化されている（Push サービス側で失効し、410 Gone / 404 Not Found を受けて自動的に無効化された）	ダッシュボードのアプリ詳細画面、または todoke apps stats <app-id> / GET /api/v1/apps/:id/stats で「アクティブ購読者」「通算送信失敗」の数値を確認する	該当ブラウザで購読をやり直す（再度 subscribe を実行する）。非アクティブ化された購読は自動復活しません
Push サービスが一時的なサーバーエラー（5xx）を返し、リトライを使い切った（メッセージ単位で 3 回リトライ後、DLQ に送られその通知は失われる）	統計の「通算送信失敗」が増えている一方、「アクティブ購読者」は減っていないことを確認する。DLQ に到達した通知は再送されません	Push サービス側の一時障害が原因のため利用者側で防ぐことはできません。届かなかった通知が重要な場合は、時間をおいて再送してください。仕組みの詳細はアーキテクチャと送信の仕組みを参照
Push サービスが 410 / 404 以外の 4xx を返した（配信失敗として記録されるのみで、リトライも購読の無効化も行われない）	「通算送信失敗」が増え続けるのに「アクティブ購読者」が減らない場合はこのケースを疑う	同じ購読に対して継続的に発生する場合は、該当ブラウザで購読を解除して登録し直してください
Free プランの月間送信上限（30,000 通）を超過している	レスポンスが 429・code: "MONTHLY_LIMIT_EXCEEDED" になっていないか確認する	プランをアップグレードするか、月が変わるまで待つ。詳細はエラーコード・制限値を参照
送信ペイロードが上限（3,072 バイト）を超えている	レスポンスが 413・code: "PAYLOAD_TOO_LARGE" になっていないか確認する	title / body / url / icon / badge の合計サイズを減らす
202 Accepted を「配信完了」と誤解している	レスポンスステータスが 202 であっても、それは Queue への投入が完了しただけであることを確認する	送信直後に届いていなくても異常とは限りません。少し時間をおいてから統計（上記）で成功・失敗を確認してください

ノート

202 Accepted は非同期配信の投入完了を示すのみで、ブラウザへの到達を保証するものではありません。詳しい配信の流れはアーキテクチャと送信の仕組みを参照してください。

2. 購読に失敗する

症状: フロントエンドで subscribe() を呼んでも購読が完了しない、またはエラーになる。

原因候補	確認方法	対処
HTTPS でないオリジンから呼び出している（Web Push は HTTPS 必須。localhost は例外）	ページの URL スキームを確認する。http:// かつ localhost 以外の場合は Push API 自体が利用できません	本番相当の環境では必ず HTTPS で配信する。開発中は http://localhost を使う
ブラウザの通知許可がブロックされている	ブラウザの Notification.permission の値（"denied" になっていないか）、またはサイト設定の通知許可状態を確認する	サイト設定から通知の許可状態を「許可」に変更してもらう。一度「ブロック」にされた許可はコードから再度ダイアログを出せません
Free プランの購読者数上限（1,000 人）を超過している	レスポンスが 429・code: "SUBSCRIBER_LIMIT_EXCEEDED" になっていないか確認する	プランをアップグレードするか、既存の非アクティブな購読を整理する。上限に達した場合、新規購読の登録で 429 が返ることがあります
Service Worker が登録されていない	navigator.serviceWorker.getRegistration() が undefined を返していないか確認する	subscribe を呼ぶ前に Service Worker の登録（navigator.serviceWorker.register(...)）を完了させる

ノート

購読者数上限の 429 が返るかどうかは、購読の登録に使用したエンドポイントによって異なる場合があります。429 が返らなくても上限付近に達している可能性はあるため、「登録できているのに上限が心配」という場合はエラーの有無で判断せず、ダッシュボードの統計（アクティブ購読者数）で実際の購読者数を確認してください。

3. 401 / 403 が返る

症状: API 呼び出しが認証・認可エラーで失敗する。

原因候補	確認方法	対処
API キーのスコープが不足している（code: "INSUFFICIENT_SCOPE"、403）	呼び出したエンドポイントが要求するスコープと、使用している API キーのスコープを比較する。スコープごとの許可操作はAPI キーを参照	より上位のスコープ（notify / full）を持つキーを使用する
API キーが URL の appId と一致していない（code: "APP_MISMATCH"、403）	リクエスト URL に含まれる appId と、使用している API キーの発行元アプリが一致しているか確認する	正しい組み合わせの appId と API キーを使用する
認証ヘッダーがない・不正、またはキー/セッションが無効（UNAUTHORIZED / INVALID_API_KEY / INVALID_SESSION、401）	Authorization: Bearer <API キー> ヘッダーが正しく付与されているか、キーが失効していないか確認する	ヘッダー形式を修正するか、ダッシュボードでキーを再発行する。セッション切れの場合は再ログインする

各コードの詳細はエラーコード・制限値を参照してください。

4. 429 が返る

症状: 短時間に繰り返しリクエストしたところ、429 エラーで拒否される。

原因候補	確認方法	対処
ログイン（POST /auth/login）のレート制限（10 回 / 60 秒 / IP）に達している	直近 60 秒以内のログイン試行回数（成功・失敗問わず）を確認する	レスポンスの Retry-After（秒）だけ待ってから再試行する
ユーザー登録（POST /auth/register）のレート制限（5 回 / 60 秒 / IP）に達している	直近 60 秒以内の登録試行回数（成功・失敗問わず）を確認する	同上。Retry-After の時間だけ待つ
API キー認証のレート制限（20 回 / 60 秒 / IP）に達している。このエンドポイントは認証失敗のみカウントされる	直近 60 秒以内に認証失敗した API リクエストの回数を確認する	Retry-After の時間だけ待つ。キーが正しく成功しているリクエストはカウントされないため、キー自体を見直すことで再発を防げる場合もある

ノート

月間送信上限（MONTHLY_LIMIT_EXCEEDED）や購読者数上限（SUBSCRIBER_LIMIT_EXCEEDED）も HTTP 429 で返りますが、これらは上記のレート制限（code: "RATE_LIMITED"）とは別の仕組みです。プラン上限超過の場合は待機ではなくプランのアップグレードが必要です。詳細はエラーコード・制限値を参照してください。

5. CORS エラー

症状: ブラウザから直接 fetch で todoke の API を呼び出すと、CORS エラーでリクエストがブロックされる。

原因候補	確認方法	対処
リクエスト元のオリジンが許可リストに含まれていない	ページのオリジンが次のいずれかに該当するか確認する: http://localhost(:port) / https://localhost(:port)、https://todoke-dashboard.pages.dev、*.todoke.dev のサブドメイン	許可されたオリジンから呼び出すか、フロントエンドから直接呼ばずに自社サーバー経由で API を呼び出す構成に変更する

注意

todoke API は上記以外のオリジンからのブラウザ直接呼び出しを許可しない設計になっています（apps/api/src/index.ts の CORS 設定）。任意のオリジンから通知送信 API を直接叩かれることを防ぐための意図的な制限であり、回避策として全オリジン許可に変更することは想定されていません。サーバーサイドから呼び出す場合は CORS の対象外なので、この制限を受けません。