# 호출 한도 (/docs/api-reference/rate-limiting)

# 호출 한도

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

## 동시 통화 한도

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

## 플랜별 한도

| 플랜 | 월 요금 | 동시 통화 수 | 월 포함량을 넘겼을 때 |
|------|---------|-------------|----------------------|
| Trial | 무료 | 1 | 제한 — 체험 기간이 끝날 때까지 발신·문자가 나가지 않습니다 |
| Individual | ₩19,000 | 1 | 계속 사용되고 초과분이 구간 단가로 청구됩니다 |
| Business | ₩99,000 | 10 | 계속 사용되고 초과분이 구간 단가로 청구됩니다 |

동시 통화 수는 아직 끝나지 않은 통화(`queued` · `initiated` · `ringing` · `in-progress`)의 합계입니다. 종료된 통화는 포함되지 않습니다.

**포함량을 넘겼을 때의 동작은 플랜마다 다릅니다.** Individual·Business 는 초과분이 구간 단가로 청구되며
계속 사용할 수 있고, Trial 은 **초과분 청구 없이 발신·문자가 제한**됩니다.

한편 **AI 에이전트·받아쓰기·요약·알림톡·브랜드 메시지·이메일·음성사서함 감지(AMD)는 플랜 포함량이
없어 모든 플랜에서 사용한 만큼 청구됩니다.** 포함량·구간 단가·플랜별 동작은 [요금](/docs/api-reference/pricing)
에 정리해 두었고, 내 계정에 적용된 포함량과 단가는 **대시보드 → 설정 → 결제**에서 볼 수 있습니다.

## 한도 초과 시 동작

### 아웃바운드 통화

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

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

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

### 이용이 제한된 계정

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

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


`ACCOUNT_RESTRICTED` 는 재시도해도 결과가 같습니다. 한도 초과(`CALL_LIMIT_EXCEEDED`)와 달리 시간이 지나도 해소되지 않습니다. SDK 는 `429` 를 자동 재시도하지만 `403` 은 재시도하지 않으므로, `RateLimitError` 가 아니라 `PermissionDeniedError` 로 잡아 즉시 중단하도록 처리하세요. 문자 발송에서는 같은 상황에 `messaging_blocked` 가 반환됩니다.

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

### 인바운드 통화

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

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

## SDK 에러 처리

### Python

```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

```typescript
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()` 사용 시에도 동일한 한도가 적용됩니다.

```python
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` 에러 코드가 반환됩니다.

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

## 문자 발송 호출 빈도

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

| 대상 | 포함 여부 |
|------|-----------|
| SMS·LMS·MMS 발송 | 포함 |
| 문자 대체발송을 켠 알림톡 | 포함 |
| 대체발송을 끈 알림톡(`Fallback.Disabled: true`)·브랜드 메시지 | 미포함 |
| 캠페인(배치) 발송 | 미포함 |
| 메시지 조회(`GET`) | 미포함 |

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

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


거절된 요청은 발송되지 않고 메시지 이력에도 남지 않습니다. `Retry-After` 의 초가 지난 뒤 같은 요청을 다시 보내세요. 대량으로 보낼 때는 분당 120건 안쪽으로 나눠 보내거나 캠페인(배치) 발송을 쓰세요.

## FAQ

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

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

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

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

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

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