요청 한도

Posmit 알림 API(/v1/notifications 계열 4개 엔드포인트)는 워크스페이스 단위와 API 키 단위로 요청 횟수를 제한합니다. 발송 요청뿐 아니라 상태 조회(GET)와 취소 요청에도 동일하게 적용됩니다.

동작 방식

고정 윈도우(fixed window) 방식입니다. 시간을 일정 길이(기본 60초)의 윈도우로 나누고, 각 윈도우 안의 요청 수를 Redis 카운터로 셉니다. 윈도우가 바뀌면 카운터는 0에서 다시 시작합니다.
한도는 HMAC 인증을 통과한 요청만 소모합니다. 401로 거부된 요청은 카운트되지 않습니다.
워크스페이스 한도를 먼저 검사하고, 그다음 API 키 한도를 검사합니다. 둘 다 통과해야 카운터가 증가하며, 초과로 거부된 요청은 카운터를 증가시키지 않습니다.

기본 한도

구분	기본값	설명
윈도우 길이	60초	카운터가 리셋되는 주기입니다.
API 키당	600 요청/윈도우	`X-API-Key`로 인증한 키 단위로 적용됩니다.
워크스페이스당	2,000 요청/윈도우	워크스페이스의 모든 API 키 사용량 합산에 적용됩니다.

여러 API 키를 사용해도 워크스페이스 한도는 합산으로 적용됩니다. 예를 들어 키 4개가 각각 600 요청을 보내면 개별 키 한도는 통과하지만 워크스페이스 한도(2,000)에서 초과가 발생합니다.

초과 시 응답

한도를 초과하면 HTTP 429와 함께 application/problem+json 에러가 반환됩니다.


{
  "type": "https://api.posmit.io/errors/noti-4291",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "API key rate limit exceeded",
  "code": "NOTI-4291",
  "instance": "/v1/notifications",
  "timestamp": "2026-07-10T09:00:00.000Z"
}

코드	의미
`NOTI-4290`	워크스페이스 한도 초과
`NOTI-4291`	API 키 한도 초과

429 응답에는 Retry-After나 X-RateLimit-* 같은 힌트 헤더가 포함되지 않으며, 남은 쿼터를 조회하는 API도 없습니다. 고정 윈도우 방식이므로 짧은 대기 후 재시도하면 다음 윈도우에서 성공합니다. 아래 재시도 가이드를 참고하세요.

클라이언트 재시도 가이드

429를 받으면 즉시 재요청하지 말고 지수 백오프 + 지터로 대기 후 재시도합니다. 윈도우 길이(기본 60초)를 넘기면 카운터가 리셋됩니다.
발송 요청을 재시도할 때는 idempotencyKey를 지정해 두면 중복 발송이 방지됩니다.
대량 발송은 단건을 반복 호출하는 대신 POST /v1/notifications/bulk(최대 500건)를 사용하면 한도 소모를 크게 줄일 수 있습니다. bulk 한 번의 호출은 요청 1회로 카운트됩니다.


async function sendWithRetry(send: () => Promise<Response>, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await send()
    if (res.status !== 429) return res
 
    // 지수 백오프 + 지터 (2s, 4s, 8s ...)
    const delay = 2000 * 2 ** attempt + Math.random() * 1000
    await new Promise((resolve) => setTimeout(resolve, delay))
  }
  throw new Error('Rate limit retries exhausted')
}

재시도하는 요청도 HMAC 서명을 새로 만들어야 합니다. X-Nonce는 1회용이고 X-Timestamp는 허용 오차(기본 ±300초)가 있으므로, 이전 요청의 헤더를 재사용하면 401이 발생합니다.

한도 확인·조정

기본 한도는 워크스페이스별 레이트리밋 정책으로 재정의할 수 있습니다. 정책 관리는 대시보드 API로 제공되며, 대시보드 로그인 세션(JWT) 인증을 사용합니다. 알림 API 키(HMAC)와는 별개입니다.

GEThttps://api.posmit.io/v1/limits/rate

현재 워크스페이스의 정책을 조회합니다. (역할: owner / admin / operator / viewer)


{
  "workspacePolicy": {
    "id": "…",
    "windowSeconds": 60,
    "maxRequests": 5000,
    "enabled": true,
    "updatedAt": "2026-07-10T09:00:00.000Z"
  },
  "apiKeyPolicies": [
    {
      "id": "…",
      "apiKeyCredentialId": "…",
      "windowSeconds": 60,
      "maxRequests": 1200,
      "enabled": true,
      "updatedAt": "2026-07-10T09:00:00.000Z"
    }
  ]
}

정책이 없으면(workspacePolicy: null, apiKeyPolicies: []) 기본 한도가 적용됩니다.

PUThttps://api.posmit.io/v1/limits/rate/workspace

워크스페이스 한도를 설정합니다. (역할: owner / admin)


curl -X PUT https://api.posmit.io/v1/limits/rate/workspace \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "windowSeconds": 60,
    "maxRequests": 5000,
    "enabled": true
  }'

PUThttps://api.posmit.io/v1/limits/rate/keys/:apiKeyCredentialId

특정 API 키의 한도를 설정합니다. (역할: owner / admin)

필드	타입	제약
`windowSeconds`	int	필수. 1 ~ 3,600
`maxRequests`	int	필수. 1 ~ 1,000,000
`enabled`	boolean	선택. `false`면 정책이 무시되고 기본 한도로 돌아갑니다.

발송 TPS 제한과의 구분

이 문서의 요청 한도는 들어오는 API 요청에 대한 제한입니다. Posmit에는 이와 별개로, 공급자로 나가는 발송 속도(TPS) 를 제어하는 디스패치 제한이 있습니다. 디스패치 제한은 요청을 거부하지 않고 발송 워커 단계에서 속도를 조절하므로 429가 발생하지 않습니다. 자세한 내용은 라우팅과 폴백을 참고하세요.