HubSpot의 10초 로링 제한: 수동 이메일 처리의 은밀한 방해 요소

원래 aideazz.xyz에서 게시되었으며, 여기에는 정식 링크와 함께 재게시되었습니다.

저는 HubSpot의 API에 막혔습니다. 제 hs-watch-manual-emails.log에는 반복적인 429 오류가 표시됩니다: "You have reached your ten_secondly_rolling limit." 이것은 단순한 가끔 발생하는 문제(hiccup)가 아니라, 수동 이메일 처리를 지속적으로 방해하는 문제입니다. 이는 제가 딜(deal) 데이터를 얼마나 빠르게 풍부하게 만들 수 있는지에 직접적인 영향을 미칩니다. 시스템은 HubSpot의 딜에서 dealname과 dealstage를 가져오도록 설계되었지만, 이 제한 때문에 해당 호출들이 자주 속도 제한(throttled)됩니다. 이 문제는 충분히 심각해서, 저는 문제와 이를 우회하려는 시도를 문서화하기 위해 2026-10-07에 제목이 hubspots-429-halting-deal-enrichment-with-a-10-second-rolling-limit/index.html인 블로그 게시물을 다시 생성했습니다.

HubSpot 로링 제한 이해하기

오류 메시지는 명확합니다: policyName이 "TEN_SECONDLY_ROLLING"입니다. 이는 HubSpot이 10초 간격의 창(window) 내에서 API 호출에 대한 제한을 적용한다는 의미입니다. 일일 또는 시간별 할당량(quota)이 아니라, 빠른 속도의 제약 조건입니다. 제 hs-watch-manual-emails.log에는 정확히 어떤 요청이 속도 제한되는지 표시됩니다: GET /crm/v3/objects/deals/[id]?properties=dealname,dealstage. 이 특정 엔드포인트는 제가 사용하는 cto-aipa 프로세스에 매우 중요하며, 이 프로세스는 198번의 재시작을 기록했고 현재 0일 동안 작동 중입니다. 이는 지속적인 불안정성 또는 최근 배포를 나타냅니다. 비교하자면, algom-stream 프로세스는 53일 동안 55193회의 재시작을 기록하여, 다른 규모의 운영상의 어려움을 강조합니다.

오류에 포함된 correlationId, 즉 01a11dbe-da9e-7b03-83fa-24150f0bd997는 이 속도 제한이 발생한 특정 사례를 확인시켜 줍니다. 이것은 모호한 API 오류가 아니라, 정확하게 정책이 시행된 것입니다.

딜 풍부화 및 수동 이메일 처리에 미치는 영향

제 hs-watch-manual-emails.log에는 거래(deal) 속성을 가져오려는 반복적인 시도와 이어서 발생하는 429 오류가 기록되어 있습니다. 이는 거래의 정보 보강(enrichment)을 직접적으로 지연시킵니다. 예를 들어, 제 HubSpot 거래 검색 API는 현재 "답장 받음(They replied)" 단계에 있는 139개의 거래를 보여줍니다. 이들 각각의 거래는 수동 이메일 처리를 통해 정보를 보강해야 할 가능성이 있습니다. API 호출이 속도 제한(throttled)되면 데이터 흐름이 느려져 거래 정보 업데이트가 지연됩니다.

reply-radar.log에는 APPLY — scanned 262 및 APPLY — scanned 263 이메일, 그리고 REPLIES MATCHED 0, errors 0으로 기록되어 있습니다. reply-radar 자체는 오류를 보고하지 않지만, 후속 작업인 hs-watch-manual-emails에서 오류가 발생하고 있습니다. 이는 이메일은 스캔되고 있지만, 관련 HubSpot 거래를 정보 보강하는 다음 단계의 행동이 속도 제한 때문에 실패하고 있음을 시사합니다. followup-radar.log는 지난 45일 동안 imap.gmail.com에 대해 받은 편지함(inbox) 이메일 702개와 전송된(sent) 이메일 4개를, 그리고 imap.zoho.com에 대해 받은 편지함 이메일 298개와 전송된 이메일 23개를 보여주며, 이는 처리되어 HubSpot 거래에 연결되어야 할 상당한 양의 이메일 트래픽이 있음을 나타냅니다.

운영 안정성 및 속도 제한 복원력

제 PM2 프로세스는 9개 중 9개가 온라인 상태이며, cto-aipa는 198번 재시작되었고 0일 동안 작동했습니다. 이는 프로세스가 재시작되고 있기는 하지만, 다운된 상태를 유지하지 못하고 있다는 것을 나타냅니다. 그러나 빈번한 재시작은 각 재시작이 API 호출의 급증(burst)을 유발할 경우 속도 제한 문제를 악화시킬 수 있습니다. 53일 동안 55193번 재시작된 algom-stream 프로세스는 실패에 대해 높은 복원력을 갖도록 설계된 시스템임을 보여주지만, 신중하게 관리되지 않으면 반복적인 API 호출의 가능성 또한 강조합니다.

pm2-logrotate 프로세스는 온라인 상태이며 5회 재시작으로 10일 동안 작동하여 로그 파일을 관리하는 데 도움을 주지만, 속도 제한(rate limiting)의 근본적인 원인을 해결하지는 못합니다. 제 github-token-watch.log를 보면 GitHub 토큰이 271일 남았다는 것을 알 수 있어, 외부 API 토큰 유효성이 문제는 아니라는 것을 나타냅니다. 문제는 전적으로 HubSpot의 TEN_SECONDLY_ROLLING 정책에 있습니다.

10초 제한 완화 전략

HubSpot의 10초 로링(rolling) 제한을 우회하기 위해, 저는 명시적인 지연 및 재시도 메커니즘을 구현해야 했습니다. 이메일이 처리되는 즉시 요청을 보내는 대신, 일시 정지(pauses)를 도입하고 있습니다. 여기에는 다음이 포함됩니다:

1. 요청 큐잉 (Queueing requests): 직접적인 API 호출 대신, 거래 강화 작업(deal enrichment tasks)을 로컬 큐에 넣습니다.
2. 속도 제한 처리 (Rate-limited processing): 별도의 워커가 이 큐에서 데이터를 가져와, HubSpot API 호출이 10초 간격을 지키도록 합니다. 이는 요청이 처리되기 전에 몇 초 동안 큐에 머무를 수 있다는 것을 의미합니다.
3. 재시도 시 지수 백오프 (Exponential backoff for retries): 429 오류가 수신되면, 시스템은 요청을 재시도하기 전에 점진적으로 더 긴 시간 동안 기다립니다. 이는 속도 제한이 즉시 다시 트리거되는 것을 방지하는 데 매우 중요합니다.

이 접근 방식은 거래 강화 프로세스에 지연 시간을 추가합니다. 수동 이메일은 처리될 수 있지만, 해당 HubSpot 거래 업데이트는 백로그와 429 오류의 빈도에 따라 몇 초 또는 심지어 몇 분 동안 지연될 수 있습니다. 목표는 즉각적이지 않더라도 궁극적인 일관성(eventual consistency)을 보장하는 것입니다.

자주 묻는 질문 (Frequently Asked Questions)

질문: 이 정책에 따라 HubSpot은 10초당 몇 개의 API 호출을 허용합니까?
답변: 오류 메시지 `policyName:

질문: 이 속도 제한이 다른 HubSpot API 엔드포인트에도 영향을 미치나요?
답변: hs-watch-manual-emails.log에 표시된 특정 오류는 GET /crm/v3/objects/deals/[id]?properties=dealname,dealstage에 관한 것입니다. 다른 엔드포인트는 제한이 다를 수 있지만, 이 로그에는 딜(deal) 속성 검색에 영향을 미치는 TEN_SECONDLY_ROLLING 정책만 표시됩니다.

질문: 귀하의 완화 전략으로 인해 발생하는 일반적인 지연 시간은 어느 정도인가요?
답변: 지연 시간은 가변적이며, 429 오류 빈도와 대기열 요청 수에 따라 달라집니다. 이 시간은 몇 초에서 몇 분까지 다양할 수 있으며, 요청이 10초 로링 제한을 준수하도록 간격을 유지합니다.

질문: 이 10초 로링 제한을 늘릴 방법이 있나요?
답변: 해당 증거에는 HubSpot의 API 속도 제한 증가를 요청하는 방법에 대한 정보가 포함되어 있지 않습니다. 저는 기존 제약 조건 내에서 시스템을 작동시키도록 조정하는 데 초점을 맞추었습니다.

— Elena Revicheva · AIdeazz · Portfolio