요청 한도

요청 한도는 갑작스러운 요청 폭주로부터 Nodaro API를 보호합니다. 각 개인 API 토큰에는 워크플로 실행에 대한 분당 한도가 있고, 일부 라우트에는 자체 한도가 있으며, 한도를 넘는 요청은 429 Too Many Requests로 응답합니다. 작업이나 실행을 폴링해도 토큰의 한도에 포함되지 않으므로, 한도 걱정 없이 몇 초마다 폴링할 수 있습니다.

토큰별 한도

모든 개인 API 토큰에는 분당 요청 한도가 있습니다.

• 기본값은 분당 30회입니다. 토큰을 만들 때 요청 한도(분당 요청 수)에서 1~120 사이로 설정합니다. 나중에 PATCH /v1/api-tokens/:id의 rateLimit으로 바꿀 수 있습니다.
• 계산되는 라우트는 두 개뿐입니다. POST /v1/api/run과 GET /v1/api/workflows입니다.
• 읽기는 계산되지 않습니다. GET /v1/api/status/:execId, GET /v1/api/result/:execId, GET /v1/api/schema는 한도를 쓰지 않습니다.
• 한도는 1분마다 초기화됩니다.

한도를 넘는 요청은 다음과 같이 응답합니다.

{ "error": { "code": "rate_limited", "message": "Too many requests. Max 30 per minute." } }

더 빠르게 보내려면 토큰의 한도를 120으로 높이세요. 그 이상이 필요하면 계정당 최대 10개까지 토큰을 더 만들고 요청을 나눠 보내세요. 인증을 참조하세요.

그 밖의 한도

서로 다른 두 가지 429 코드

• rate_limited는 /v1/api/ 라우트의 토큰별 한도에서만 나옵니다.
• rate_limit_exceeded는 그 밖의 모든 한도에서 나옵니다. 토큰이 필요 없는 일부 라우트의 IP 주소별 한도, 특정 라우트의 호출자별 한도, 게시된 앱의 일일 실행 한도입니다.

호출자별 한도가 있는 라우트는 Retry-After 헤더를 보냅니다. 크레딧을 쓰는 라우트에서 서버가 한도를 확인할 수 없으면 503 rate_limit_unavailable로 응답합니다.

재시도 로직은 429 상태를 기준으로 만드세요. 코드는 토큰별 한도와 그 밖의 한도를 구분할 때만 사용하세요.

한도 대처 요령

• 2~5초마다 폴링하세요. 실행 상태는 몇 초 만에 바뀌므로, 더 자주 폴링해도 얻는 것이 없습니다.
• 한 번의 호출로 여러 작업을 폴링하세요. GET /v1/jobs/status와 POST /v1/jobs/batch-status는 각각 최대 100개의 작업을 반환합니다. 작업을 참조하세요.
• 429에서는 지수적으로 백오프하세요. 재시도할 때마다 5초, 10초, 20초를 기다리세요. Retry-After가 있으면 최소 그 시간만큼 기다리세요.
• 다른 4xx 오류는 최종 오류로 취급하세요. 재시도하지 말고 요청을 고치세요. 오류를 참조하세요.

import { RateLimitedError } from '@nodaro/sdk'

async function withBackoff<T>(call: () => Promise<T>): Promise<T> {
  for (const seconds of [5, 10, 20]) {
    try {
      return await call()
    } catch (err) {
      if (!(err instanceof RateLimitedError)) throw err
      await new Promise((r) => setTimeout(r, seconds * 1_000))
    }
  }
  return call()
}

const { executionId } = await withBackoff(() => client.workflows.run(workflowId))

일괄 처리와 페이지 크기