호출 한도

ClawOps는 두 가지 한도를 적용합니다. 통화는 구독 플랜에 따른 동시 통화 수, 문자는 분당 발송 요청 수입니다.

동시 통화 한도

ClawOps는 구독 플랜에 따라 계정당 동시에 진행할 수 있는 통화 수를 제한합니다. 인바운드와 아웃바운드 통화를 합산하여 계산합니다.

플랜별 한도

한도 초과 시 동작

아웃바운드 통화

calls.create() 호출 시 동시 통화 한도를 초과하면 HTTP 429 응답과 함께 CALL_LIMIT_EXCEEDED 에러 코드가 반환됩니다.

{
  "error": "Concurrent call limit: 1/1",
  "code": "CALL_LIMIT_EXCEEDED"
}

error 는 현재 진행 중인 통화 수/한도 형식입니다. 문구는 안내용이므로 분기는 code 로 하세요. 이 응답은 슬롯이 비면 성공하므로 잠시 후 재시도하면 됩니다.

이용이 제한된 계정

계정의 발신이 제한된 상태에서 calls.create() 를 호출하면 HTTP 403 응답과 함께 ACCOUNT_RESTRICTED 에러 코드가 반환됩니다.

{
  "error": "발신이 제한된 계정입니다. 고객센터로 문의해 주세요.",
  "code": "ACCOUNT_RESTRICTED"
}

제한 사유와 해제 절차는 계정에 등록된 이메일로 안내되며, 대시보드 상단에도 표시됩니다.

인바운드 통화

동시 통화 한도를 초과한 상태에서 전화가 수신되면, 발신자에게 자동으로 안내 멘트("현재 통화 중입니다. 잠시 후 다시 걸어주세요.")가 재생된 후 통화가 종료됩니다.

이 통화도 통화 기록에 남습니다. status 는 busy, hangupCause 는 concurrency_limit_exceeded 입니다. 해당 번호에 Status Callback 을 등록하셨다면 CallStatus=busy · Duration=0 으로 발송되므로, 발신번호(From)를 받아 콜백 안내 문자를 보내는 구성에 쓰실 수 있습니다. 사유별 조회 방법은 통화 실패 사유 를 참고하세요.

SDK 에러 처리

Python

from clawops import ClawOps, RateLimitError

client = ClawOps()

try:
    call = client.calls.create(
        to="01012345678",
        from_="07052358010",
        url="https://my-app.com/twiml",
    )
except RateLimitError as e:
    print(f"동시 통화 한도 초과: {e.message}")

Node.js

import ClawOps, { RateLimitError } from 'clawops';

const client = new ClawOps();

try {
  const call = await client.calls.create({
    to: '01012345678',
    from: '07052358010',
    url: 'https://my-app.com/twiml',
  });
} catch (e) {
  if (e instanceof RateLimitError) {
    console.log(`동시 통화 한도 초과: ${e.message}`);
  }
}

Voice Agent

Voice Agent SDK의 agent.call() 사용 시에도 동일한 한도가 적용됩니다.

from clawops.agent import ClawOpsAgent, AgentError

agent = ClawOpsAgent(...)

try:
    call = await agent.call(to="01012345678")
except AgentError as e:
    if getattr(e, "status", None) == 429:
        print("동시 통화 한도 초과")

구독 없음 (403)

활성 구독이 없는 계정에서 통화를 시도하면 HTTP 403 응답과 함께 NO_SUBSCRIPTION 에러 코드가 반환됩니다.

{
  "error": "활성 구독이 없습니다",
  "code": "NO_SUBSCRIPTION"
}

문자 발송 호출 빈도

문자 발송은 계정당 분당 120건, API 키당 분당 120건까지 받습니다. 한 계정이 여러 API 키나 경로(REST API·MCP send_message·대시보드 문자 보내기)로 보내도 계정 기준으로 합산됩니다.

한도는 매 분 정각을 기준으로 초기화됩니다. 한도를 넘으면 HTTP 429 응답과 함께 rate_limited 에러 코드가 반환되고, Retry-After 헤더에 다시 시도할 수 있을 때까지 남은 초가 담깁니다.

{
  "error": "문자 발송은 계정당 분당 120건까지입니다. 49초 뒤 다시 시도해 주세요",
  "code": "rate_limited"
}

FAQ

한도를 늘리려면 어떻게 하나요?

대시보드에서 상위 플랜으로 업그레이드하면 동시 통화 한도가 자동으로 증가합니다.

인바운드와 아웃바운드를 별도로 제한할 수 있나요?

아닙니다. 동시 통화 한도는 인바운드와 아웃바운드를 합산하여 적용됩니다.

통화가 종료되면 즉시 슬롯이 해제되나요?

네. 통화가 종료(completed/failed)되면 즉시 슬롯이 해제되어 새로운 통화가 가능합니다.