速率限制与用量

月度提取限额

每个计划包含固定数量的每月提取次数。用量在每月第一天（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."
  }
}

您有两个选择：

1. 升级计划。 前往 DocMap 控制面板的 设置 > 账单。新的限额立即生效。
2. 等待下一个计费周期。 用量在每月第一天（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.");
      // Optionally check current usage
      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;
}

用量预警

当您的用量达到月度限额的 80% 时，DocMap 会自动发送电子邮件通知。这让您有时间在提取被暂停前升级计划。

• 预警在每个计费周期仅发送一次 -- 您不会收到重复邮件
• 邮件包含您当前的用量、限额和直接升级链接
• 仅账户所有者会收到用量预警邮件

TIP

在启动大规模批量操作之前，通过调用 GET /v1/usage 以程序化方式监控用量。这让您可以检查是否有足够的剩余额度。

请求速率限制

除月度提取限额外，过高的请求频率可能会被限流以保护服务稳定性。为避免限流：

• 在批量请求之间添加延迟。 处理大量文件时，在连续 API 调用之间添加小延迟（例如 200--500 毫秒），而不是同时发送所有请求。
• 使用并发限制。 如果并行处理文件，将并发限制在 5--10 个同时请求。
• 监控响应时间。 如果响应时间显著增加，请降低请求频率。

// Process files with controlled concurrency
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);

    // Brief pause between batches
    if (i + concurrency < files.length) {
      await new Promise((resolve) => setTimeout(resolve, 500));
    }
  }

  return results;
}