エラーコード・制限値

エラーレスポンス形式

API がエラーを返す場合、HTTP ステータスコードとともに以下の JSON 形式のボディを返します。

{
  "error": "人間可読なエラーメッセージ",
  "code": "MACHINE_READABLE_CODE"
}

error: 日本語の人間可読メッセージです。画面表示にそのまま使えますが、分岐処理には code を使ってください。
code: プログラムで判定するための機械可読コードです。本ページの一覧に固定値として列挙されています。

{
  "error": "月間送信上限に達しました",
  "code": "MONTHLY_LIMIT_EXCEEDED",
  "upgrade_url": "https://todoke.dev/#pricing"
}

エラーコード一覧

code	HTTP	意味	対処
`MISSING_FIELDS`	400	必須フィールドが欠落しています	リクエストボディの必須項目を確認してください
`INVALID_URL`	400	`url` / `icon` / `badge` / `endpoint` が `https://` で始まっていません	対象フィールドを `https://` の URL に修正してください
`INVALID_ENDPOINT`	400	`endpoint` の形式が不正です	ブラウザの Push API から取得した `endpoint` をそのまま送信してください
`TOO_MANY_ENDPOINTS`	400	バッチ送信の `endpoints` が上限（100 件）を超えています	100 件以下に分割して送信してください
`INVALID_EMAIL`	400	メールアドレスの形式が不正です（認証系）	メールアドレスの形式を確認してください
`INVALID_INPUT`	400	入力値が不正です（認証系。例: パスワードが長すぎる）	入力値の形式・長さを確認してください
`INVALID_SCOPE`	400	API キー作成時に指定した scope 名が不正です	`subscribe_only` / `notify` / `full` のいずれかを指定してください
`MISSING_CODE`	400	GitHub OAuth コールバックに `code` パラメータがありません	OAuth フローを最初からやり直してください
`UNAUTHORIZED`	401	認証ヘッダーがない、または不正です	`Authorization: Bearer <API キー>` ヘッダーを付与してください
`INVALID_API_KEY`	401	API キーが無効です	キーの値を確認するか、ダッシュボードで再発行してください
`INVALID_SESSION`	401	セッションが無効です	再ログインしてください
`INVALID_CREDENTIALS`	401	メールアドレスまたはパスワードが正しくありません	入力内容を確認してください
`INSUFFICIENT_SCOPE`	403	API キーのスコープが不足しています	より上位のスコープ（`notify` / `full`）のキーを使用してください
`APP_MISMATCH`	403	API キーが URL の appId と一致していません	URL の appId と、使用している API キーの発行元アプリを確認してください
`PLAN_LIMIT_EXCEEDED`	403	Free プランのアプリ数上限（1）を超過しています	既存アプリを削除するか、プランをアップグレードしてください
`INVALID_STATE`	403	GitHub OAuth の state パラメータが不一致です	OAuth フローを最初からやり直してください
`NOT_FOUND`	404	指定したリソースが存在しません	アプリ ID・キー ID などの指定値を確認してください
`EMAIL_IN_USE`	409	メールアドレスが既に登録済みです	別のメールアドレスを使用するか、ログインしてください
`PAYLOAD_TOO_LARGE`	413	送信ペイロードが上限（3,072 バイト）を超えています	`title` / `body` / `url` / `icon` / `badge` の合計サイズを減らしてください
`MONTHLY_LIMIT_EXCEEDED`	429	Free プランの月間送信上限（30,000 通）を超過しています（`upgrade_url` 付き）	プランをアップグレードするか、翌月まで待ってください
`SUBSCRIBER_LIMIT_EXCEEDED`	429	Free プランの購読者数上限（1,000 人）を超過しています（`upgrade_url` 付き）	プランをアップグレードするか、購読者数を整理してください
`RATE_LIMITED`	429	レート制限を超過しました	`Retry-After` ヘッダー（秒）の時間を待ってから再試行してください
`GITHUB_AUTH_FAILED`	502	GitHub との OAuth 認証に失敗しました	しばらく待って再度ログインを試してください
`OAUTH_NOT_CONFIGURED`	503	サーバー側で GitHub OAuth が設定されていません	管理者に問い合わせてください（GitHub ログインは利用不可）
`CONFIG_ERROR`	503	サーバー側の設定不備です（暗号化キー・ペッパー未設定など）	管理者に問い合わせてください
`INTERNAL_ERROR`	500	未処理の例外が発生しました	しばらく待って再試行し、解消しない場合はサポートに連絡してください

レート制限

以下のエンドポイントは IP アドレス単位でレート制限されています。

対象	制限
ログイン（`POST /auth/login`）	10 回 / 60 秒
GitHub OAuth 開始（`GET /auth/github`）	10 回 / 60 秒（ログインとカウンタを共有）
ユーザー登録（`POST /auth/register`）	5 回 / 60 秒
API キー認証エンドポイント	20 回 / 60 秒

制限を超過すると HTTP 429（code: "RATE_LIMITED"）が返り、Retry-After: 60 ヘッダーが付与されます。

プラン制限（Free プラン）

項目	上限	超過時のエラーコード
アプリ数	1	`PLAN_LIMIT_EXCEEDED`（403）
購読者数	1,000	`SUBSCRIBER_LIMIT_EXCEEDED`（429）
月間送信数	30,000 通	`MONTHLY_LIMIT_EXCEEDED`（429）

いずれの上限超過時もレスポンスにアップグレード導線 upgrade_url（https://todoke.dev/#pricing）が含まれます。

送信ペイロード制限

ペイロードサイズ: title / body / url / icon / badge を JSON にエンコードした UTF-8 サイズで 3,072 バイトまで。超過すると PAYLOAD_TOO_LARGE（413）
バッチ送信件数: POST /api/v1/notify/batch の endpoints は 100 件まで。超過すると TOO_MANY_ENDPOINTS（400）
URL 形式: url / icon / badge / endpoint は https:// のみ許可されます。http:// を指定すると INVALID_URL（400）