일일 메시지 한도
모든 플랜에는 하루에 보낼 수 있는 메시지 수가 정해져 있습니다. 횟수는 UTC 기준 00:00에 초기화됩니다. 한도에 도달하면 초기화 전까지 새 메시지는 429 Too Many Requests와 함께 거부됩니다. 이런 메시지는 저장되지 않으며 푸시 알림도 전송되지 않습니다.
플랜별 한도
| 플랜 | 일일 메시지 수 |
|---|---|
| 무료 플랜 | 50 |
| Starter | 1,000 |
| Medium | 5,000 |
| Large | 무제한 |
현재 플랜과 오늘의 사용량은 결제 페이지에서 확인할 수 있으며, GET /v1/messages/usage를 통해 API로도 조회할 수 있습니다.
집계 기준
계정에서 생성된 모든 메시지는 생성된 UTC 날짜에 한 번씩 집계됩니다.
- API 요청 —
POST /v1/messages요청이며, 첨부 파일이 포함된 요청도 포함됩니다. - 웹훅 호출 — 메시지를 생성하는 각 호출입니다.
- 예약 메시지 — 전송되는 날이 아니라 예약하는 날에 집계됩니다. 오늘 예약해 다음 주 화요일에 보낼 메시지는 오늘의 한도를 사용합니다. 실제 전송은 한도를 사용하지 않으며 한도 때문에 막히지도 않습니다.
다음은 집계되지 않습니다.
- 유효성 검사에 실패(
400,403)하거나 서버 측에서 실패(500)한 요청은 한도가 복구됩니다. - 거부된 요청 자체는 놓친 알림을 확인할 수 있도록
rejected로 별도 집계됩니다.
메시지를 삭제해도 한도는 돌아오지 않습니다
이 카운터는 저장된 메시지가 아니라 전송된 메시지를 기준으로 합니다. 메시지를 하나씩 삭제하거나 한꺼번에 삭제해도 오늘의 한도는 돌아오지 않습니다.
한도에 도달했을 때
API는 초기화까지 남은 초 수를 담은 429 Too Many Requests 헤더와 함께 Retry-After를 응답합니다.
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{
"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"
}연동에서 429 처리하기
429는 일시적인 실패가 아니라 "지금은 안 됨"으로 취급하세요. Retry-After가 지나기 전에 재시도하면 같은 응답을 받게 되며, 재시도 요청도 거부되고 집계됩니다. resets_at까지 기다리거나, 알림을 버리고 로그에 기록하세요.
curl --retry는 자정까지 멈출 수 있습니다
curl --retry는 429를 재시도 대상으로 보고 Retry-After를 따르므로, 한도를 넘긴 스크립트는 UTC 00:00까지 대기하게 됩니다. --retry-max-time으로 대기 시간을 제한하세요.
curl --retry 3 --retry-max-time 60 -X POST "https://api.pocketalert.app/v1/messages" ...웹훅
한도를 넘긴 웹훅 호출도 같은 429로 거부되지만, 각 호출은 웹훅의 기록에 전체 페이로드와 생성되었을 메시지와 함께 남습니다. 해당 항목에는 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%에 도달했을 때 — 아직 여유가 있을 때 미리 알려 드리는 안내입니다.
- 첫 거부 메시지가 발생했을 때 — 한도에 도달해 새 메시지가 거부되고 있다는 안내입니다.
무제한 플랜에는 이 이메일이 발송되지 않습니다.
플랜 업그레이드
새 플랜은 즉시 적용됩니다. 업그레이드가 완료되면 다음 요청부터 새 한도로 확인되므로 초기화 시각까지 기다릴 필요가 없습니다. 가격 정책을 참고하세요.