Лимиты и использование

Ежемесячные лимиты извлечений

Каждый план включает фиксированное количество извлечений в календарный месяц. Использование сбрасывается в первый день каждого месяца (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;
}

Предупреждения об использовании

DocMap автоматически отправляет email-уведомление, когда использование достигает 80% ежемесячного лимита. Это дает вам время для перехода на более высокий план до приостановки извлечений.

• Предупреждение отправляется один раз за период оплаты -- вы не будете получать повторные письма
• Письмо содержит текущее количество использований, лимит и прямую ссылку на страницу перехода на другой план
• Предупреждения об использовании получает только владелец аккаунта

TIP

Программно отслеживайте использование, вызывая GET /v1/usage перед запуском крупных пакетных операций. Это позволяет проверить, достаточно ли у вас оставшейся емкости.

Ограничения частоты запросов

В дополнение к ежемесячным лимитам извлечений, чрезмерная частота запросов может быть ограничена для защиты стабильности сервиса. Чтобы избежать ограничения:

• Добавляйте задержки между пакетными запросами. При обработке множества файлов добавляйте небольшую задержку (например, 200--500 мс) между последовательными API-вызовами вместо одновременной отправки всех запросов.
• Используйте ограничение параллелизма. При параллельной обработке файлов ограничьте параллелизм до 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;
}