연동을 붙이고 두 달쯤 지나 어느 날 갑자기 동기화가 멈춥니다. 로그를 열면 한도 초과 오류가 찍혀 있습니다. 코드에는 아무 문제가 없습니다.
Zoho CRM의 API는 호출 수가 아니라 크레딧 단위로 계산되고, 일일 한도가 에디션과 사용자 수로 결정됩니다. 그리고 호출 종류마다 소모하는 크레딧이 다릅니다.
이 구조를 모르고 연동을 설계하면 개발이 끝난 뒤에 한도에 부딪힙니다. 그때 해결 방법은 에디션 상향이거나 연동 재설계인데, 둘 다 비쌉니다.
이 글은 공식 개발자 문서 기준으로 크레딧 계산 공식과 실제 소요량 산출 방법을 정리합니다. 확인일은 2026년 9월 21일입니다.
1. 한도는 '호출 수'가 아니라 '크레딧'입니다
많은 연동 설계가 '하루 몇 번 호출하는가'로 시작합니다. Zoho CRM에서는 이 접근이 맞지 않습니다.
공식 개발자 문서 기준, 대부분의 API 호출은 1크레딧을 소모하지만 무거운 작업은 더 많이 소모합니다. 예를 들어 리드 전환(Convert Lead) API는 호출당 5크레딧, 대량 쓰기 초기화(Bulk Write Initialize)는 500크레딧입니다.
반대로 삽입·수정·업서트는 레코드 10건당 1크레딧입니다. 즉 1,000건을 한 번에 넣으면 100크레딧입니다. 건별로 1,000번 호출하면 1,000크레딧입니다.
같은 일을 하는데 설계에 따라 소모량이 열 배 차이가 납니다. 이것이 크레딧 구조를 먼저 이해해야 하는 이유입니다.
2. 일일 한도 공식 — 에디션과 사용자 수로 결정됩니다
공식 개발자 문서 기준, 일일 크레딧은 24시간 롤링 윈도로 계산되며 에디션별 공식이 다릅니다.
Free는 5,000크레딧 고정입니다. Standard는 50,000 + (사용자 수 × 250)이며 상한 100,000입니다. Professional은 50,000 + (사용자 수 × 500)이며 상한 300만입니다.
Enterprise와 Zoho One은 50,000 + (사용자 수 × 1,000)이며 상한 500만입니다. Ultimate와 CRM Plus는 50,000 + (사용자 수 × 2,000)이며 상한이 없습니다.
여기서 중요한 것은 사용자 수가 한도에 직접 들어간다는 점입니다. 사용자 10명의 Standard는 50,000 + 2,500 = 52,500크레딧이고, 이것이 하루 전체 연동이 쓸 수 있는 전부입니다.
3. 동시 호출 수라는 두 번째 한도
일일 크레딧이 남아 있어도 막히는 경우가 있습니다. 동시 호출 수 제한 때문입니다.
공식 문서 기준 조직 단위 동시 호출 한도는 Free 5, Standard 10, Professional 15, Enterprise·Zoho One 20, Ultimate·CRM Plus 25입니다.
여기에 더해 리드 전환, 복잡한 쿼리, 대량 수정 같은 무거운 작업에는 전 에디션 공통으로 10이라는 별도 하위 동시성 한도가 적용됩니다.
배치 작업을 병렬로 돌리는 설계에서 이 한도에 먼저 걸립니다. 스레드 수를 에디션 한도 아래로 고정하고, 재시도 로직에 지수 백오프를 넣으십시오.
4. 소요량을 계산하는 방법
계산은 연동 시나리오별로 '하루 몇 번 × 회당 크레딧'을 더하는 방식입니다. 시나리오를 빠짐없이 적는 것이 계산의 정확도를 결정합니다.
빠지기 쉬운 것들이 있습니다. 실시간 웹훅에 대응하는 조회 호출, 실패 시 재시도, 개발·테스트 환경의 호출, 리포트 도구의 주기적 추출, 그리고 사용자가 직접 실행하는 수동 동기화.
특히 재시도가 문제입니다. 실패한 호출도 크레딧을 소모합니다. 오류율 5%에 3회 재시도 설계면 실질 소모량이 15% 늘어납니다.
계산이 끝나면 여유율을 둡니다. 실무 권장은 산출값의 1.5배가 일일 한도 안에 들어오는지 확인하는 것입니다. 성수기나 일괄 처리일에 소모량이 몰리기 때문입니다.
5. 크레딧을 줄이는 네 가지 설계
첫째, 건별 호출을 배치로 바꿉니다. 삽입·수정은 10건당 1크레딧이므로 묶을수록 유리합니다. 100건을 건별로 넣으면 100크레딧, 한 번에 넣으면 10크레딧입니다.
둘째, 전체 동기화를 증분 동기화로 바꿉니다. 마지막 동기화 시각 이후 변경된 레코드만 가져오면 조회량이 크게 줄어듭니다.
셋째, 폴링을 웹훅으로 바꿉니다. 5분마다 변경을 확인하는 설계는 하루 288번 조회합니다. 변경 시점에 알림을 받는 방식이면 실제 변경 건수만큼만 호출합니다.
넷째, 대량 작업은 Bulk API를 씁니다. 초기화에 500크레딧이 들지만 수만 건을 처리한다면 건별 호출보다 압도적으로 적습니다. 반대로 수백 건이면 일반 API가 낫습니다. 손익분기를 계산해 선택하십시오.
6. 초기 이관은 별도로 계산하십시오
운영 중 연동과 초기 데이터 이관은 성격이 다릅니다. 이관은 짧은 기간에 대량으로 몰립니다.
이관을 API로 수행할 계획이라면 일일 한도에 반드시 걸립니다. 수만 건 규모면 며칠에 나눠 처리하거나, API가 아닌 가져오기 기능을 쓰는 편이 낫습니다.
Zoho CRM은 파일 가져오기와 마이그레이션 마법사를 제공하며, 이 경로는 API 크레딧과 별개입니다. 이관은 이 경로를 우선 검토하십시오.
이관 후 검증을 API로 돌리는 경우도 크레딧을 소모합니다. 검증 쿼리를 건별이 아니라 집계로 설계하면 소모량이 크게 줄어듭니다.
7. 한도에 걸렸을 때 확인할 순서
먼저 어느 한도인지 구분합니다. 일일 크레딧 초과인지, 동시 호출 초과인지, 하위 동시성 초과인지. 오류 코드와 메시지가 다릅니다.
일일 크레딧 초과면 소모량 상위 시나리오를 찾습니다. 대개 하나의 폴링 작업이나 재시도 루프가 전체의 절반 이상을 쓰고 있습니다.
동시 호출 초과면 병렬 처리 수를 줄이고 큐를 둡니다. 코드 수정으로 해결되는 경우가 많아 비용이 가장 적게 듭니다.
에디션 상향은 마지막 수단입니다. 설계를 고치지 않고 에디션만 올리면 사용량이 늘었을 때 같은 문제가 다시 생기고, 그때는 올릴 에디션이 없습니다.
8. 연동 설계 문서에 반드시 들어가야 할 항목
연동을 외주로 맡기든 내부에서 만들든, 설계 문서에 다음 항목이 있어야 합니다. 시나리오 목록, 시나리오별 일일 호출 횟수와 회당 크레딧, 합계와 여유율, 에디션 한도 대비 사용률.
여기에 재시도 정책, 동시 실행 수, 오류 처리와 알림 방식을 함께 적습니다. 이 문서가 없으면 한도 초과가 났을 때 원인을 찾는 데만 며칠이 걸립니다.
견적을 받을 때도 이 문서를 근거로 요구하십시오. 크레딧 계산이 들어 있지 않은 연동 견적은 나중에 재설계 비용이 붙을 가능성이 높습니다.
운영 단계에서는 사용률을 주간 단위로 기록하십시오. 사용률 추이를 보면 한도에 언제 도달할지 미리 알 수 있습니다.
9. 확인되지 않은 것
크레딧 소모량은 API 버전과 엔드포인트에 따라 달라질 수 있습니다. 이 글의 수치는 확인 시점의 공식 개발자 문서 기준이며, 구현 전에 해당 엔드포인트 문서에서 직접 확인하십시오.
Zoho One과 CRM Plus 사용자의 한도는 CRM 단품과 다르게 적용될 수 있으므로 계약 구성에 맞는 문서를 확인해야 합니다.
일부 부가 제품(Analytics, Flow 등)과의 연동은 별도 한도 체계를 가질 수 있습니다. 이 글은 Zoho CRM API에 한정합니다.
확인하지 못한 수치는 적지 않았습니다. 연동 설계는 추정치로 하면 반드시 나중에 비용이 됩니다.
에디션별 API 한도 (공식 개발자 문서 기준)
|
에디션 |
일일 크레딧 공식 |
상한 |
동시 호출 |
|---|---|---|---|
|
Free |
5,000 고정 |
5,000 |
5 |
|
Standard / Starter |
50,000 + (사용자수 × 250) |
100,000 |
10 |
|
Professional |
50,000 + (사용자수 × 500) |
3,000,000 |
15 |
|
Enterprise / Zoho One |
50,000 + (사용자수 × 1,000) |
5,000,000 |
20 |
|
Ultimate / CRM Plus |
50,000 + (사용자수 × 2,000) |
상한 없음 |
25 |
|
무거운 작업 하위 동시성 |
전 에디션 공통 |
— |
10 |
출처: Zoho CRM API v8 공식 문서 (2026.09.21 확인) · 24시간 롤링 윈도 기준 · 사용자 수가 한도에 직접 반영됩니다
크레딧 소모 계산 예시 — 사용자 10명 Standard (한도 52,500)
|
연동 시나리오 |
일일 호출 |
회당 크레딧 |
일일 크레딧 |
|---|---|---|---|
|
ERP 거래처 동기화 (증분, 5분 주기) |
288 |
1 |
288 |
|
ERP 수주 등록 (배치, 50건 묶음) |
20 |
5 (50건÷10) |
100 |
|
홈페이지 폼 → 리드 생성 |
150 |
1 |
150 |
|
리드 전환 (Convert Lead) |
30 |
5 |
150 |
|
BI 도구 일일 추출 (집계 쿼리) |
24 |
1 |
24 |
|
실패 재시도 (오류율 5% · 3회) |
— |
— |
약 106 |
|
합계 |
— |
— |
약 818 |
|
여유율 1.5배 적용 |
— |
— |
약 1,227 (한도의 2.3%) |
이 예시는 계산 방법을 보여주기 위한 가상의 연동 구성입니다. 실제 소모량은 엔드포인트와 구현 방식에 따라 달라지므로 구현 전 공식 문서로 확인하십시오
자주 묻는 질문
Q. 일일 한도는 자정에 초기화되나요?
공식 문서는 24시간 롤링 윈도 방식으로 설명하고 있습니다. 즉 특정 시각에 일괄 초기화되는 것이 아니라 직전 24시간 동안의 소모량으로 계산됩니다. 따라서 '자정 이후에 배치를 몰아서 돌린다'는 설계는 기대만큼 효과가 없습니다.
Q. 사용자를 늘리면 한도도 늘어나나요?
공식에 사용자 수가 들어가므로 늘어납니다. 다만 에디션별 상한이 있어 무한정 늘지는 않습니다. Standard는 상한 100,000이므로 사용자 200명을 넘으면 더 늘지 않습니다. 한도 때문에 사용자를 늘리는 것은 라이선스 비용이 더 크므로 설계 개선이 우선입니다.
Q. 대량 이관도 API 크레딧을 쓰나요?
API로 수행하면 씁니다. Zoho CRM이 제공하는 파일 가져오기와 마이그레이션 마법사를 이용하는 경로는 API 크레딧과 별개이므로, 초기 이관은 이 경로를 먼저 검토하십시오. 다만 가져오기에는 파일당 레코드 수와 파일 크기 한도가 에디션별로 따로 있습니다.
Q. 한도 초과가 이미 발생했습니다. 무엇부터 봐야 하나요?
먼저 오류가 일일 크레딧 초과인지 동시 호출 초과인지 구분하십시오. 동시 호출이면 병렬 수를 줄이는 코드 수정으로 대부분 해결됩니다. 일일 크레딧이면 소모량 상위 시나리오를 찾으십시오. 대개 하나의 폴링 작업이나 재시도 루프가 절반 이상을 쓰고 있습니다.
이 글이 다루지 않는 것
이 글은 Zoho CRM API의 크레딧과 동시성 한도를 다룹니다. 개별 엔드포인트의 사용법, 인증 구현 방법, Zoho Analytics·Flow 등 부가 제품의 별도 한도 체계는 다루지 않습니다. 수치는 확인 시점의 공식 개발자 문서 기준이며 API 버전에 따라 달라질 수 있습니다.
함께 읽으면 좋은 글
이 글은 P3 구축과 운영 시리즈의 일부입니다.
출처
- Forrester, The State Of Business Buying, 2024 (2024.12) — forrester.com/press-newsroom
- 6sense, 2025 B2B Buyer Experience Report (2025.11) — 6sense.com
- Gartner B2B 구매자 조사 (2025.05 발표, 632명) — gartner.com/en/newsroom
- Salesforce, State of Sales 6th·7th Edition (2024.07 / 2026.02) — salesforce.com
- Zoho One 가격 페이지 및 FAQ (2026.09.12 확인) — zoho.com/one/pricing
- Zoho Agents 가격 페이지 — zoho.com/agents/pricing
- Zoho 가격 변경 공지 페이지 — zoho.com/price-change-notice.html
- Nucleus Research, Zoho ROI 조사 (2025.02) — zoho.com 게시 자료
본문의 원화 환산은 1 USD = 1,380원, 기준일 2026년 9월 12일을 적용했습니다. 요금과 약관은 변경될 수 있으므로 계약 전 공식 페이지에서 재확인하십시오.
