レート制限と使用量

月間抽出制限

各プランには、暦月あたりの固定された抽出回数が含まれています。使用量は毎月1日（UTC）にリセットされます。

プラン	月間抽出回数	価格
Free	25	$0
Starter	350	-
Core	2,500	-
Pro	10,000	-

TIP

現在のプラン料金と機能比較については docmap.io/#pricing をご覧ください。

使用量の確認

/v1/usage エンドポイントをクエリして、現在のプラン、使用回数、アクティブな請求期間の制限を確認します：

curl

curl https://api.docmap.io/v1/usage \
  -H "Authorization: Bearer dm_live_your_api_key"

TypeScript

const response = await fetch("https://api.docmap.io/v1/usage", {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const { data } = await response.json();

console.log(`Plan: ${data.plan}`);
console.log(`Usage: ${data.usage} / ${data.limit}`);
console.log(`Period: ${data.periodKey}`);

Python

import requests

response = requests.get(
    "https://api.docmap.io/v1/usage",
    headers={"Authorization": f"Bearer {api_key}"},
)

data = response.json()["data"]

print(f"Plan: {data['plan']}")
print(f"Usage: {data['usage']} / {data['limit']}")
print(f"Period: {data['periodKey']}")

レスポンス例：

{
  "data": {
    "plan": "core",
    "usage": 1847,
    "limit": 2500,
    "periodKey": "2025-07"
  }
}

フィールド	説明
plan	現在のプラン: free、starter、core、または pro
usage	現在の請求期間で使用された抽出回数
limit	プランで許可される最大抽出回数
periodKey	現在の請求期間（YYYY-MM 形式）

制限超過時の処理

月間制限に達すると、POST /v1/extractions/run へのすべてのコールは 429 ステータスと USAGE_LIMIT_EXCEEDED エラーコードを返します：

{
  "error": {
    "code": "USAGE_LIMIT_EXCEEDED",
    "message": "Monthly extraction limit reached (25/25). Upgrade your plan for more extractions."
  }
}

2つの選択肢があります：

1. プランをアップグレードする。 DocMapダッシュボードの 設定 > 課金 に移動してください。新しい制限は即座に有効になります。
2. 次の請求期間を待つ。 使用量は毎月1日（UTC）に自動的にリセットされます。

WARNING

429 USAGE_LIMIT_EXCEEDED エラーをリトライしないでください。サーバーエラーとは異なり、これらは自然に解決されません。バッチリクエストを行う前に /v1/usage エンドポイントで現在のカウントと制限を確認してください。

コード内で適切に処理する方法は以下のとおりです：

async function runExtraction(templateId: string, fileName: string, pdfBase64: string) {
  const response = await fetch("https://api.docmap.io/v1/extractions/run", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ templateId, fileName, pdfBase64, mimeType: "application/pdf" }),
  });

  if (response.status === 429) {
    const { error } = await response.json();
    if (error.code === "USAGE_LIMIT_EXCEEDED") {
      console.error("Monthly extraction limit reached. Upgrade your plan or wait until next month.");
      // オプションで現在の使用量を確認
      const usageResponse = await fetch("https://api.docmap.io/v1/usage", {
        headers: { Authorization: `Bearer ${apiKey}` },
      });
      const { data: usage } = await usageResponse.json();
      console.log(`Current usage: ${usage.usage}/${usage.limit} (${usage.plan} plan)`);
      return null;
    }
  }

  const { data } = await response.json();
  return data;
}

使用量の警告

DocMapは、使用量が月間制限の 80% に達した時点で自動的にメール通知を送信します。これにより、抽出が一時停止される前にプランをアップグレードする時間が得られます。

• 警告は 請求期間ごとに1回 送信されます -- 繰り返しメールは送信されません
• メールには現在の使用回数、制限、アップグレードへの直接リンクが含まれます
• 使用量警告メールはアカウント所有者のみが受信します

TIP

大規模なバッチ操作を開始する前に GET /v1/usage を呼び出して、プログラムで使用量を監視してください。これにより、十分な残容量があるかどうかを確認できます。

リクエストレート制限

月間抽出制限に加えて、サービスの安定性を保護するために、過度なリクエストレートがスロットリングされる場合があります。スロットリングを避けるには：

• バッチリクエスト間に遅延を追加する。 多数のファイルを処理する場合、すべてを同時に送信するのではなく、連続するAPIコール間に少しの遅延（例：200〜500ミリ秒）を追加してください。
• 同時実行数を制限する。 ファイルを並列処理する場合、同時リクエスト数を5〜10に制限してください。
• レスポンス時間を監視する。 レスポンス時間が大幅に増加した場合は、リクエストレートを下げてください。

// 制御された同時実行でファイルを処理
async function processFilesWithLimit(files: string[], concurrency = 5) {
  const results = [];

  for (let i = 0; i < files.length; i += concurrency) {
    const batch = files.slice(i, i + concurrency);

    const batchResults = await Promise.all(
      batch.map((file) => runExtraction("tmpl_abc123", file, encode(file)))
    );

    results.push(...batchResults);

    // バッチ間の短い一時停止
    if (i + concurrency < files.length) {
      await new Promise((resolve) => setTimeout(resolve, 500));
    }
  }

  return results;
}