# 일일 메시지 한도

모든 플랜에는 하루에 보낼 수 있는 메시지 수가 정해져 있습니다. 횟수는 **UTC 기준 00:00**에 초기화됩니다. 한도에 도달하면 초기화 전까지 새 메시지는 `429 Too Many Requests`와 함께 거부됩니다. 이런 메시지는 저장되지 않으며 푸시 알림도 전송되지 않습니다.

## 플랜별 한도

| 플랜 | 일일 메시지 수 |
|------|-----------------:|
| 무료 플랜 | 50 |
| Starter | 1,000 |
| Medium | 5,000 |
| Large | 무제한 |

현재 플랜과 오늘의 사용량은 [결제](https://pocketalert.app/account/billing) 페이지에서 확인할 수 있으며, [`GET /v1/messages/usage`](https://info.pocketalert.app/api/messages/usage.md)를 통해 API로도 조회할 수 있습니다.

## 집계 기준

계정에서 생성된 모든 메시지는 생성된 UTC 날짜에 한 번씩 집계됩니다.

- **API 요청** — [`POST /v1/messages`](https://info.pocketalert.app/api/messages/create.md) 요청이며, 첨부 파일이 포함된 요청도 포함됩니다.
- **웹훅 호출** — 메시지를 생성하는 각 호출입니다.
- **예약 메시지** — 전송되는 날이 아니라 **예약하는** 날에 집계됩니다. 오늘 예약해 다음 주 화요일에 보낼 메시지는 오늘의 한도를 사용합니다. 실제 전송은 한도를 사용하지 않으며 한도 때문에 막히지도 않습니다.

다음은 집계되지 않습니다.

- 유효성 검사에 실패(`400`, `403`)하거나 서버 측에서 실패(`500`)한 요청은 한도가 복구됩니다.
- 거부된 요청 자체는 놓친 알림을 확인할 수 있도록 `rejected`로 별도 집계됩니다.

> **Warning: 메시지를 삭제해도 한도는 돌아오지 않습니다**
>
> 이 카운터는 저장된 메시지가 아니라 전송된 메시지를 기준으로 합니다. 메시지를 하나씩 삭제하거나 한꺼번에 삭제해도 오늘의 한도는 돌아오지 않습니다.

## 한도에 도달했을 때

API는 초기화까지 남은 초 수를 담은 `429 Too Many Requests` 헤더와 함께 `Retry-After`를 응답합니다.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 30142
X-PA-Daily-Limit: 50
X-PA-Daily-Remaining: 0
X-PA-Daily-Reset: 1790035200
```

```json
{
  "error": "Daily message limit reached (50/50). New messages are rejected until 00:00 UTC. Upgrade your plan to raise the limit.",
  "limit": 50,
  "used": 50,
  "resets_at": "2026-09-22T00:00:00Z",
  "upgrade_url": "https://pocketalert.app/pricing"
}
```

> **Tip: 연동에서 429 처리하기**
>
> `429`는 일시적인 실패가 아니라 "지금은 안 됨"으로 취급하세요. `Retry-After`가 지나기 전에 재시도하면 같은 응답을 받게 되며, 재시도 요청도 거부되고 집계됩니다. `resets_at`까지 기다리거나, 알림을 버리고 로그에 기록하세요.

> **Warning: `curl --retry`는 자정까지 멈출 수 있습니다**
>
> `curl --retry`는 `429`를 재시도 대상으로 보고 `Retry-After`를 따르므로, 한도를 넘긴 스크립트는 UTC 00:00까지 대기하게 됩니다. `--retry-max-time`으로 대기 시간을 제한하세요.
>
> ```bash
> curl --retry 3 --retry-max-time 60 -X POST "https://api.pocketalert.app/v1/messages" ...
> ```

### 웹훅

한도를 넘긴 웹훅 호출도 같은 `429`로 거부되지만, 각 호출은 웹훅의 [기록](https://info.pocketalert.app/api/webhooks/history.md)에 전체 페이로드와 생성되었을 메시지와 함께 남습니다. 해당 항목에는 `status: "error"`와 `error_code: "daily_limit"`이 기록되므로, 한도를 초과한 동안 들어온 요청은 기록에서 확인할 수 있습니다.

## 한도 관련 헤더

성공한 `POST /v1/messages` 요청(및 메시지를 생성한 모든 웹훅 호출)에는 현재 한도 정보가 담긴 헤더가 포함됩니다.

| 헤더 | 의미 |
|--------|---------|
| `X-PA-Daily-Limit` | 플랜에서 하루에 허용되는 메시지 수 |
| `X-PA-Daily-Remaining` | 이 메시지를 포함해 오늘 남은 메시지 수 |
| `X-PA-Daily-Reset` | 다음 초기화 시각(UTC 00:00)의 유닉스 타임스탬프(초) |

무제한 플랜에는 이 헤더가 제공되지 않습니다.

## 이메일 알림

Pocket Alert는 계정 소유자에게 하루에 최대 두 번 이메일을 보냅니다.

- **일일 한도의 80%에 도달했을 때** — 아직 여유가 있을 때 미리 알려 드리는 안내입니다.
- **첫 거부 메시지가 발생했을 때** — 한도에 도달해 새 메시지가 거부되고 있다는 안내입니다.

무제한 플랜에는 이 이메일이 발송되지 않습니다.

## 플랜 업그레이드

새 플랜은 즉시 적용됩니다. 업그레이드가 완료되면 다음 요청부터 새 한도로 확인되므로 초기화 시각까지 기다릴 필요가 없습니다. [가격 정책](https://pocketalert.app/pricing)을 참고하세요.

## 관련 문서

- [메시지 생성](https://info.pocketalert.app/api/messages/create.md) — 맥락에서 보는 `429` 응답
- [메시지 사용량](https://info.pocketalert.app/api/messages/usage.md) — API로 확인하는 오늘의 사용량
- [웹훅 기록](https://info.pocketalert.app/api/webhooks/history.md) — 거부된 웹훅 호출이 보관되는 곳
- [예약 발송](https://info.pocketalert.app/features/scheduled-delivery.md) — 예약 메시지가 집계되는 방식
