요금 제한 및 사용량

월간 추출 한도

각 플랜에는 매월 고정된 추출 횟수가 포함됩니다. 사용량은 매월 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에 대한 모든 호출은 USAGE_LIMIT_EXCEEDED 오류 코드와 함께 429 상태를 반환합니다:

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

두 가지 옵션이 있습니다:

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.");
      // 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은 사용량이 월간 한도의 **80%**에 도달하면 자동으로 이메일 알림을 보냅니다. 이를 통해 추출이 중단되기 전에 플랜을 업그레이드할 시간을 확보할 수 있습니다.

• 경고는 청구 기간당 한 번 전송됩니다 -- 반복 이메일을 받지 않습니다
• 이메일에는 현재 사용 횟수, 한도, 업그레이드 직접 링크가 포함됩니다
• 계정 소유자만 사용량 경고 이메일을 받습니다

TIP

대규모 배치 작업을 시작하기 전에 GET /v1/usage를 호출하여 프로그래밍 방식으로 사용량을 모니터링하세요. 이를 통해 남은 용량이 충분한지 확인할 수 있습니다.

요청 속도 제한

월간 추출 한도 외에도 서비스 안정성을 보호하기 위해 과도한 요청 속도가 제한될 수 있습니다. 제한을 피하려면:

• 배치 요청 사이에 지연을 추가하세요. 많은 파일을 처리할 때 동시에 모두 보내는 대신 연속 API 호출 사이에 작은 지연(예: 200--500ms)을 추가하세요.
• 동시성 제한을 사용하세요. 파일을 병렬로 처리하는 경우 동시 요청을 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;
}