コンテンツにスキップ
todoke docs

エラーコード・制限値

エラーレスポンス形式

Section titled “エラーレスポンス形式”

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

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

POST /auth/register、POST /auth/login、POST /api/v1/apps、POST /api/v1/apps/:id/keys、POST /api/v1/notify、POST /api/v1/notify/batch で壊れた JSON を送ると、必須項目が不足した場合と同じ 400 MISSING_FIELDS を返します。 /mcp では JSON-RPC のパースエラーとして HTTP 200 とエラーコード -32700 を返します。

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

エラーコード一覧

Section titled “エラーコード一覧”
codeHTTP意味対処
MISSING_FIELDS400必須項目が欠落しているか、項目の型が不正ですリクエストボディの必須項目と各項目の型を確認してください
INVALID_BODY400PATCH /api/v1/me の本文が不正です（壊れた JSON、email_notifications の欠落・型不正、未知の項目）email_notifications だけを持つ JSON オブジェクトを送り、値を boolean にしてください
INVALID_FIELDS400POST /api/v1/notify と /batch の dry_run が boolean でないか、POST /api/v1/apps/:id/notify に endpoint / endpoints が指定されていますdry_run を boolean にし、全購読者への手動送信では endpoint / endpoints を除いてください
INVALID_URL400url / icon / badge / endpoint が https:// で始まっていません対象フィールドを https:// の URL に修正してください
INVALID_ENDPOINT400endpoint の形式が不正ですブラウザの Push API から取得した endpoint をそのまま送信してください
TOO_MANY_ENDPOINTS400バッチ送信の endpoints が上限（100 件）を超えています100 件以下に分割して送信してください
INVALID_EMAIL400メールアドレスの形式が不正です（認証系）メールアドレスの形式を確認してください
INVALID_INPUT400入力値が不正です（認証系。例: パスワードが長すぎる）入力値の形式・長さを確認してください
INVALID_SCOPE400API キー作成時に指定した scope 名が不正ですsubscribe_only / notify / full のいずれかを指定してください
MISSING_CODE400GitHub OAuth コールバックに code パラメータがありませんOAuth フローを最初からやり直してください
INVALID_STATUS400GET /api/v1/apps/:id/subscriptions の status が不正ですactive / inactive / all のいずれかを指定してください
INVALID_LIMIT400一覧取得の limit が範囲外、または整数ではありませんGET /api/v1/apps/:id/subscriptions は 1〜200、同じアプリの /key-events / /webhook-deliveries / /notifications は 1〜100 の整数を指定してください
INVALID_BEFORE400購読者一覧・キー操作履歴・Webhook 配信履歴・通知履歴の before / before_id が不正ですbefore は 0 以上の整数、before_id は空白だけでない値を before と対で指定してください。履歴 API の before は空文字・空白を避け、JavaScript の安全な整数範囲内にしてください
MISSING_SIGNATURE400POST /stripe/webhook に Stripe-Signature ヘッダーがありませんStripe から署名付きで配信してください
INVALID_SIGNATURE400POST /stripe/webhook の署名検証に失敗しましたWebhook の署名シークレットを確認し、署名検証前の本文を改変しないでください
NO_SUBSCRIPTION400POST /api/v1/billing/portal で Stripe の顧客情報が見つかりませんPro へのアップグレード手続きを確認し、未手続きなら Checkout から開始してください
UNAUTHORIZED401認証ヘッダーがない、または不正ですAuthorization: Bearer <API キー> ヘッダーを付与してください
INVALID_API_KEY401API キーが無効ですキーの値を確認するか、ダッシュボードで再発行してください
INVALID_SESSION401セッションが無効です再ログインしてください
INVALID_CREDENTIALS401メールアドレスまたはパスワードが正しくありません入力内容を確認してください
INSUFFICIENT_SCOPE403API キーのスコープが不足していますより上位のスコープ（notify / full）のキーを使用してください
APP_MISMATCH403API キーが URL の appId と一致していませんURL の appId と、使用している API キーの発行元アプリを確認してください
PLAN_LIMIT_EXCEEDED403Free プランのアプリ数上限（1）を超過しています既存アプリを削除するか、プランをアップグレードしてください
PLAN_REQUIRED403PATCH /api/v1/apps/:id で Pro 以外のプランから Webhook を設定しようとしています（upgrade_url 付き）Pro にアップグレードしてください。Webhook の解除は Free でも可能です
INVALID_STATE403GitHub OAuth の state パラメータが不一致ですOAuth フローを最初からやり直してください
NOT_FOUND404指定したリソースが存在しませんアプリ ID・キー ID などの指定値を確認してください
EMAIL_IN_USE409メールアドレスが既に登録済みです別のメールアドレスを使用するか、ログインしてください
ALREADY_SUBSCRIBED409POST /api/v1/billing/checkout を呼んだユーザーが既に Pro です契約や支払い方法の変更には /api/v1/billing/portal を使ってください
ALREADY_VERIFIED409POST /api/v1/me/verification-email でメールアドレスが既に確認済みです確認メールの再送は不要です
NO_DELIVERABLE_EMAIL409POST /api/v1/me/verification-email で登録アドレスが @noreply.todoke のため確認メールを送れません到達可能なメールアドレスで利用する方法をサポートに問い合わせてください
SUBSCRIPTION_EXPIRED410POST /api/v1/apps/:id/test-notification で Push サービスが 404 / 410 を返しましたブラウザで購読を登録し直してからテスト送信してください
PAYLOAD_TOO_LARGE413送信ペイロードが上限（3,072 バイト）を超えていますtitle / body / url / icon / badge の合計サイズを減らしてください
MONTHLY_LIMIT_EXCEEDED429Free プランの月間送信上限（30,000 通）を超過しています（upgrade_url 付き）プランをアップグレードするか、翌月まで待ってください
SUBSCRIBER_LIMIT_EXCEEDED429Free プランの購読者数上限（1,000 人）を超過しています（upgrade_url 付き）プランをアップグレードするか、購読者数を整理してください
RATE_LIMITED429レート制限を超過しましたRetry-After ヘッダー（秒）の時間を待ってから再試行してください
TOO_MANY_REQUESTS429POST /api/v1/me/verification-email が再送待機期間中です前回の再送要求から 10 分経過してから再試行してください
GITHUB_AUTH_FAILED502GitHub との OAuth 認証に失敗しましたしばらく待って再度ログインを試してください
STRIPE_ERROR502Checkout・Customer Portal のセッション作成、または DELETE /api/v1/me に伴う Stripe 契約の解約に失敗しましたしばらく待って再試行し、解消しない場合はサポートに連絡してください
PUSH_FAILED502POST /api/v1/apps/:id/test-notification で送信処理が例外になったか、Push サービスが 2xx・404・410 以外を返しました購読情報を確認して再試行し、解消しない場合はサポートに連絡してください
OAUTH_NOT_CONFIGURED503サーバー側で GitHub OAuth が設定されていません管理者に問い合わせてください（GitHub ログインは利用不可）
CONFIG_ERROR503サーバー側の設定不備です（暗号化キー・ペッパー未設定など）管理者に問い合わせてください
INTERNAL_ERROR500未処理の例外が発生しましたしばらく待って再試行し、解消しない場合はサポートに連絡してください

レート制限

Section titled “レート制限”

以下のエンドポイントは 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 プラン）

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

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

送信ペイロード制限

Section titled “送信ペイロード制限”
  • ペイロードサイズ: 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 は https:// のみ許可されます。http:// を指定すると INVALID_URL（400）
  • endpoint: POST /api/v1/notify の endpoint と /batch の endpoints は 1 件 2,048 バイトまでで、https:// かつ内部ホスト（localhost・プライベート IP など）以外である必要があります。満たさないと INVALID_ENDPOINT（400）。購読登録時と同じ検査です