제한과 정책
이름 기반 Workflow 실행에는 Workflow별 한도와 API 토큰별 한도가 각각 적용돼요.
두 한도 중 하나라도 초과하면 요청은 HTTP 429 rate_limited로 거절돼요.
호출 레이트 리밋
각 Workflow와 API 토큰에는 분·시간·일 단위 호출 한도가 적용돼요.
각 한도는 다음 상한을 넘을 수 없고, Workflow와 토큰에 더 낮은 값을 설정할 수 있어요.
| 기간 | 상한 |
|---|---|
| 분 | 120회 |
| 시간 | 3,600회 |
| 일 | 50,000회 |
플랜별 API 토큰의 기본 분당 한도와 계정 수량 한도는 다음과 같아요.
| 플랜 | 토큰 기본 분당 호출 수 | 기기 수 | Workflow 수 |
|---|---|---|---|
| Free | 60회 | 2 | 5 |
| Pro | 600회 | 10 | 50 |
한도를 초과하면 응답에 제한 범위(workflow 또는 token), 기간(minute, hour, day), 한도와 관측 횟수가 포함돼요.
이 응답에는 Retry-After 헤더가 제공되지 않아요.
Workflow와 토큰 한도는 별도로 계산돼요.
요청을 처리하려면 두 한도를 모두 만족해야 해요.
기기 실행 빈도 제한
워크플로우 YAML의 limits로 Agent 기기에서 실행 빈도를 제한할 수 있어요.
이 설정은 위의 서버 호출 한도와 별도로 적용되며, 두 제한을 모두 통과해야 실행돼요.
Agent의 제한 판정은 서버가 작업을 보낸 뒤 비동기로 이뤄져요.
기기 제한에 걸려도 HTTP 429가 아니라 HTTP 201 작업 응답으로 처리돼요.
wait: true로 호출하고 대기 시간 안에 작업이 끝나면 최종 status: "rejected"와 reason: "rate_limited"가 응답에 담겨요.
대기 시간이 끝나면 timedOut: true가 오고 status는 queued 또는 running일 수 있어요.
대기 없이 호출하면 접수 상태만 반환되며, 결과는 consoleUrl의 콘솔 작업 화면에서 확인해주세요.
설정 방법과 제한 유형은 워크플로우 YAML의 실행 빈도 제한을 참고해주세요.
호출 요청 옵션
POST /v1/run/{agentName}/{workflowName}에는 레이트 리밋을 우회하는 force 옵션이 없어요.
그래서 이 경로로 들어오는 실행에는 YAML limits도 항상 적용돼요.
debug: true는 지원되지 않으며, 요청에 포함하면 HTTP 400 invalid_request로 거절돼요.
중복 요청 방지 (Idempotency)
Idempotency-Key 헤더를 사용하면 같은 Agent와 Workflow에서 같은 키로 재호출할 때 기존 Job을 반환해요.
다른 요청 본문에 같은 키를 사용하면 HTTP 409 idempotency_conflict가 반환돼요.
curl --fail-with-body -sS -X POST \
"https://api.deplite.io/v1/run/prod-server/deploy" \
-H "Authorization: Bearer ${DEPLITE_API_TOKEN}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: deploy-2026-10-15-001" \
-d '{"ref":"main","wait":true}'기존 요청의 Job이 반환되면 응답에 idempotent: true가 포함돼요.
실전 시나리오
A — 배포 호출 폭주 제한
같은 Workflow로 여러 배포 요청이 한꺼번에 들어오는 상황을 대비해 Workflow나 토큰에 낮은 호출 한도를 설정할 수 있어요.
한도를 넘은 요청은 HTTP 429 rate_limited로 거절돼요.
B — 콘솔에서 Workflow 실행
콘솔의 Workflow 화면에서 지금 실행을 선택하면 ref와 params를 입력해 호출할 수 있어요.
결과를 기다리려면 wait를 지정해주세요.