한도
보낼 수 있는 요청 수.
분당 요청 수
각 엔드포인트는 분당 정해진 수의 요청을 허용해요. 데이터 엔드포인트와 계정 읽기에서는 한 계정의 모든 키와 토큰이 함께 계산돼요. 거부된 요청을 포함해 모든 요청이 계산돼요.
| 엔드포인트 | 항목 | 분당 한도 |
|---|---|---|
| fetch-organization | 회사 프로필 | 60 |
| fetch-person | 인물 프로필 | 60 |
| search-organizations | 검색 및 내보내기 | 60 |
| fetch-document | 문서 | 5 |
| signals | Signals | 60 |
| account | 계정 읽기 | 30 |
| account, auth/tokens | Bearer 토큰 관리; 키, 모니터, 웹훅 엔드포인트 생성, 수정, 삭제 | 10 |
| account/webhook-endpoints | 웹훅 엔드포인트 확인과 테스트, 시크릿 교체 | 6 |
검색, 문서, Signals는 분당 60 요청의 한도를 공유해요. 문서에는 별도의 더 작은 한도도 있어요.
계정, Monitoring, 웹훅에 대한 쓰기 요청도 계정 한도에 포함돼요. 같은 숫자가 각 엔드포인트 페이지의 “비용과 한도”에도 있어요.
한도는 모든 크레딧 구독에서 같아요. 분당 요청이 더 필요하면 Enterprise 계약으로 더 높은 한도를 받을 수 있어요.
한도 도달
한도를 넘으면 API가 429로 응답해요. 헤더 Retry-After가 몇 초 뒤에 다시 요청할 수 있는지 알려 줘요. 같은 숫자가 필드 retry_after에도 있어요.
모든 응답은 헤더로 남은 여유를 보여 줘요:
| 헤더 | 의미 | 예시 |
|---|---|---|
| X-RateLimit-Limit | 이 엔드포인트의 분당 한도. |
30 |
| X-RateLimit-Remaining | 이번 1분 동안 더 보낼 수 있는 요청 수. |
0 |
| Retry-After |
429에서만: 다음 요청이 가능해질 때까지의 초.
|
17 |
| X-RateLimit-Reset |
429에서만: 계속할 수 있는 시각(Unix 시간).
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
요청을 많이 보낸다면 X-RateLimit-Remaining을 지켜보고, API가 429로 응답하기 전에 스스로 속도를 줄이세요. 한도를 넘은 요청은 비용이 들지 않아요.
타임아웃
대부분의 응답은 몇 초 안에 와요. AI 모드, news 기능, 실시간 조회, fetch-person, 문서는 문서와 실시간 데이터를 등기부에서 직접 가져오므로 더 오래 걸려요.
특히 실시간 모드, fetch-person, 문서를 위해 클라이언트 타임아웃을 최소 120초로 설정하세요. 타임아웃이 너무 짧으면 거의 끝나 가는 요청이 중단돼요.
문서에는 async=true도 있어요: API가 바로 202로 응답하고 백그라운드에서 문서를 가져와요. fetch-document를 참고하세요.
408을, 문서는 Retry-After와 함께 504를 받아요. 과금되지 않아요. 조금 뒤에 요청을 다시 시도하세요. 실시간 모드의 실시간 조회만 실패하면 실시간 추가 요금 없이 저장된 데이터로 회사 프로필을 받아요.
이중 과금 없이 재시도
클라이언트가 요청을 중단해도 저희 쪽에서는 요청이 끝나 과금될 수 있어요. 헤더 Idempotency-Key를 쓰면 그때의 재시도는 비용이 들지 않아요.
요청마다 별도의 키를 고르고, 재시도할 때 그대로 보내세요. 키는 1~128자이며 문자, 숫자, 마침표, 밑줄, 콜론, 하이픈으로 이루어지고 문자나 숫자로 시작해요.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: YOUR_API_KEY" \ -H "Idempotency-Key: hetzner-profile-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| 경우 | 데이터 엔드포인트 | Monitoring과 웹훅 |
|---|---|---|
| 키 필수 여부 | 아니요, 선택 |
예, 없으면 428
|
| 유효 기간 | 24시간 | 24시간 |
| 같은 키, 같은 파라미터 | 과금 없이 결과를 다시 받음 | 저장된 응답과 그 상태 |
| 같은 키, 다른 파라미터 |
422 idempotency_key_reused |
409 idempotency_conflict |
| 오류 뒤 | 키를 계속 쓸 수 있음 | 같은 오류가 다시 옴, 새 키 필요 |
데이터 엔드포인트
fetch-organization, fetch-person, search-organizations, fetch-document는 키를 선택 사항으로 받아요. 24시간 안에 같은 키와 같은 파라미터로 요청을 반복하면 과금 없이 결과를 다시 받아요.
첫 응답에는 헤더 Idempotency-Status: created가, 재시도마다 Idempotency-Status: replayed와 meta.request_credit_cost: 0이 붙어요. 재시도에는 잔액이 필요 없어요.
결과가 전달되어야만 키가 묶여요. 그래서 오류 뒤에는 같은 키를 계속 쓸 수 있어요. 같은 키를 다른 파라미터로 쓰면 idempotency_key_reused와 함께 422가 와요. 데이터 엔드포인트는 다른 형식의 키를 무시하므로 형식을 정확히 지키세요.
signals는 Idempotency 키를 받지 않아요.
1{2 "error": "idempotency_key_reused",3 "message": "This Idempotency-Key was already used with different parameters.",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
Monitoring과 웹훅
/v1/account/monitors, /v1/account/webhook-endpoints, /v1/account/webhook-deliveries에 대한 쓰기 요청에는 키가 필요해요. 키가 없으면 API가 428로 응답하고, 형식이 틀린 키는 400을 받아요.
24시간 안에 같은 키와 같은 파라미터로 보내면 저장된 응답이 상태와 함께 Idempotency-Status: replayed를 달고 돌아와요. 오류에도 적용돼요. 그래서 다시 확인하기 같은 새 시도에는 새 키를 써요.
같은 키를 다른 파라미터로 쓰면 idempotency_conflict와 함께 409가 와요. 첫 요청이 아직 실행 중이면 idempotency_in_progress와 함께 409를 받아요.
재시도 계획
모든 오류가 두 번째 시도를 할 가치가 있지는 않아요. 이렇게 하세요:
- 재시도:
408,Retry-After이후의429,5xx. 시도 사이의 대기 시간을 매번 늘리고(예: 2초, 4초, 8초), 몇 번 시도한 뒤에는 멈추세요. - 먼저 고친 뒤 다시 보내기:
400,401,402,403,404,422. 같은 요청을 다시 보내면 같은 결과가 와요. - 유료 요청에는 Idempotency 키를 보내세요. 그러면 중단 뒤의 재시도는 비용이 들지 않아요.