오류와 한도
하나로 통일된 오류 형식, 모든 오류 코드, 요청 ID, 플랜별 요청 한도, 검색과 집계의 한도, 일일 한도, 페이지, 안전한 재시도를 설명합니다.
하나로 통일된 오류 형식
모든 오류 응답은 같은 모양입니다. 무엇을 할지는 error.code를 읽고 판단하고, 사람에게는 error.message를 보여 주세요. 메시지는 쉬운 문장 하나입니다.
{
"error": {
"code": "insufficient_credits",
"message": "Revealing these people costs 1 credit each and the account has none left. Pick a plan at https://argorant.com/pricing.",
"details": { "needed": 25, "balance": 0 }
},
"request_id": "req_8f2c1d9e0b7a4c3e9f1a2b3c4d5e6f70",
"detail": "..."
}detail에는 이 형식 이전에 작성된 클라이언트를 위한 예전 형태의 오류가 들어 있습니다. 새 코드는 error를 읽어야 합니다.
오류 코드
| 코드 | 상태 | 의미와 대처 방법 |
|---|---|---|
invalid_request | 400 | 요청에 빠진 것이 있거나 값이 잘못되었습니다. 메시지에 고칠 부분이 나옵니다. |
launch_blocked | 400 | 캠페인을 아직 시작할 수 없습니다. details.blockers에 빠진 항목이 나옵니다. |
unauthorized | 401 | API 키가 없거나, 키가 잘못되었거나 취소되었습니다. |
api_key_required | 401 | 이 경로에는 브라우저 세션이 아니라 API 키나 커넥터 로그인이 필요합니다. |
plan_required | 402 | 계정의 플랜에 이 기능이 포함되어 있지 않습니다. 메시지에 이 기능이 포함된 플랜이 나옵니다. 플랜도 크레딧도 없는 계정의 키는 모든 호출에서 이 코드를 받습니다. |
insufficient_credits | 402 | 이 호출에 필요한 크레딧이 부족합니다. details에 필요한 크레딧 수가 나옵니다. 비용은 청구되지 않았습니다. |
scope_missing | 403 | 키에 이 호출에 필요한 범위가 없습니다. 그 범위를 가진 키를 만드세요. |
permission_missing | 403 | 워크스페이스에서의 역할로는 이 작업을 할 수 없습니다. |
forbidden | 403 | 이 계정에는 허용되지 않는 작업입니다. |
not_found | 404 | 워크스페이스에 해당 항목이 없습니다. 다른 워크스페이스의 항목도 같은 방식으로 응답합니다. |
route_not_found | 404 | 해당 엔드포인트가 없습니다. 레퍼런스와 경로를 대조해 보세요. |
method_not_allowed | 405 | 경로는 있지만 이 HTTP 메서드로는 쓸 수 없습니다. details.allowed에 사용할 수 있는 메서드가 나옵니다. |
conflict | 409 | 항목이 이 작업을 허용하지 않는 상태입니다. 예를 들어 실행 중인 캠페인을 삭제하려는 경우입니다. |
idempotency_conflict | 409 | 이 Idempotency-Key는 이미 다른 본문과 함께 사용되었습니다. |
idempotency_in_progress | 409 | 이 Idempotency-Key를 사용한 요청이 아직 실행 중입니다. 기다렸다가 다시 시도하세요. |
gone | 410 | 항목이 만료되었습니다. 예를 들어 보관 기간이 지난 내보내기 파일입니다. |
quote_expired | 410 | 견적이 너무 오래되었습니다. 새 견적을 받고 다시 확인하세요. |
validation_error | 422 | 필드의 타입이 잘못되었거나 필드가 빠졌습니다. details.fields에 문제가 하나씩 나옵니다. |
access_key_activation_required | 428 | 초대받은 이 액세스 키는 아직 활성화되지 않았습니다. 먼저 details.claim_url에서 이메일을 확인하세요. |
rate_limited | 429 | 이번 1분 또는 10초 동안 요청이 너무 많았거나, 이번 1분 동안 검색과 집계가 너무 많았거나, 1분에 200명을 넘게 공개했습니다. Retry-After초만큼 기다리세요. |
daily_limit_reached | 429 | 일일 한도를 다 썼습니다. 이런 종류의 호출에 대한 키의 한도이거나, 플랜이 없는 계정의 하루 새 이메일 한도입니다. details.action에 어느 한도인지 나옵니다. UTC 자정에 초기화됩니다. |
internal_error | 500 | 저희 쪽에서 문제가 생겼습니다. 다시 시도하고, 계속 실패하면 요청 ID를 알려 주세요. |
unavailable | 503 | 서비스의 일부가 바쁘거나 일시정지되어 있습니다. 1분 뒤에 다시 시도하세요. |
confirmation_required | 400 | 주문에는 confirmed=true가 필요하며, 결제하는 사람이 승인한 뒤에만 보내야 합니다. |
invalid_webhook_url | 400 | 웹훅 주소는 공개된 https:// 주소여야 합니다. |
invalid_webhook_events | 400 | 알 수 없는 이벤트 이름이 있거나 이벤트가 지정되지 않았습니다. details.invalid에 알 수 없는 이름이 나옵니다. |
webhook_limit_reached | 400 | 켜져 있는 웹훅이 10개이거나, 꺼진 것을 포함해 모두 50개입니다. 먼저 하나를 삭제하거나 끄세요. 팀 멤버마다 따로 가집니다. |
event_not_subscribed | 400 | 테스트 호출에 웹훅이 받지 않는 이벤트를 지정했습니다. details.events에 웹훅이 받는 이벤트가 나옵니다. |
company_credits_required | 402 | 전체 기업 프로필에는 크레딧이 들며 계정의 크레딧이 부족합니다. details.teaser에 무료 부분이 들어 있고, 비용은 청구되지 않았습니다. |
search_busy | 503 | 지금 검색이 바쁩니다. 몇 초 뒤에 다시 시도하세요. |
phones_not_in_plan | 402 | 전화번호는 Pro 플랜부터 제공됩니다. 비용은 청구되지 않았습니다. |
card_not_charged | 402 | 저장된 카드로 결제되지 않았습니다. 구매된 것은 없으니 결제 링크로 결제하세요. |
owner_only | 403 | 워크스페이스 소유주만 할 수 있는 작업입니다. 예를 들어 메일함 주문이나 해지입니다. |
quote_not_found | 404 | 견적이 없거나 다른 사람의 것입니다. 새 견적을 받으세요. |
charge_in_progress | 409 | 지금 이 견적이 결제되는 중입니다. 잠시 뒤 주문을 확인하세요. |
not_enough_names | 409 | 사용 가능한 도메인 이름을 충분히 찾지 못했습니다. 도메인을 직접 몇 개 보내 주세요. |
not_paid | 409 | 주문이 아직 결제되지 않아서 해지할 것이 없습니다. |
reason_required | 422 | 메일함을 해지하려면 제시된 선택지 중에서 사유를 골라야 합니다. |
not_connected | 409 | 그 도구가 아직 연결되지 않았습니다. 먼저 설정의 연결된 도구에서 연결하세요. |
unsupported_tool | 409 | 이 연결된 도구는 인물을 직접 받을 수 없습니다. 대신 내보내기 페이지에서 내보내기를 보내세요. |
tool_key_rejected | 409 | 연결된 도구가 저장된 키를 받아들이지 않았습니다. 설정의 연결된 도구에서 다시 연결하세요. |
price_mismatch | 409 | 상대에게 보여 준 가격이 견적 가격과 다릅니다. 견적 가격을 보여 주고 다시 물어보세요. |
quote_other_session | 409 | 견적이 다른 키나 연결로 만들어졌습니다. 여기서 새 견적을 요청하고 다시 확인하세요. |
export_failed | 409 | 내보내기가 끝나지 않아서 보낼 것이 없습니다. 내보내기를 다시 실행하세요. |
sign_in_failed | 422 | 메일 서버가 로그인을 받아들이지 않아 메일함이 연결되지 않았습니다. details.test에 발송과 답장 읽기 각각에서 무엇이 잘못되었는지 나옵니다. |
campaign_not_started | 409 | 캠페인이 초안이라서 일시정지할 것이 없습니다. 먼저 시작하세요. |
finder_rate_limit | 429 | 이번 1분 동안 이메일 찾기 단건 조회가 30회를 넘었습니다. Retry-After초만큼 기다리세요. |
finder_daily_limit | 429 | 오늘 이메일 찾기 조회가 2,000회에 도달했습니다. UTC 자정에 초기화됩니다. |
finder_miss_rate_throttle | 429 | 최근 조회 대부분이 아무것도 찾지 못해서, 한동안 조회 속도가 시간당 20회로 낮춰집니다. 이름과 도메인을 확인하세요. |
일부 작업에는 confirmation_required나 quote_not_found처럼 고유한 코드가 더 있습니다. 각 작업의 코드는 레퍼런스에 나와 있습니다. 모르는 코드는 HTTP 상태에 따라 처리하세요.
요청 ID
모든 응답에는 X-Request-Id 헤더가 있고, 모든 오류는 이 값을 request_id로 다시 담습니다. 내 로그에서 호출을 찾으려면 X-Request-Id 헤더에 직접 정한 ID(영문자, 숫자, 점, 하이픈, 밑줄로 8~64자)를 보내세요. 도움을 요청할 때 이 ID를 알려 주세요.
분당 요청 수
각 키는 1분에 다음 수만큼 요청을 보낼 수 있고, 10초 동안에는 두 번째 숫자까지 보낼 수 있습니다.
| 플랜 | 분당 요청 수 | 10초 동안 |
|---|---|---|
| 플랜 없음, API 키 또는 CLI | 30 | 15 |
| 플랜 없음, AI 어시스턴트 | 60 | 20 |
| Starter | 60 | 15 |
| Pro | 240 | 60 |
| Scale | 600 | 150 |
| Hyperscale | 1,200 | 300 |
플랜 없음은 아직 플랜을 고르지 않은 계정의 처음 7일과, 이전에 구매한 크레딧을 쓰는 계정에 해당합니다. 플랜 체험에는 그 플랜의 한도가 적용됩니다. 플랜도 크레딧도 없는 계정의 키는 GET /api/v1/account를 포함해 모든 호출에서 402 plan_required를 받습니다.
키로 보낸 호출의 모든 응답에는 X-RateLimit-Limit(분당 요청 수), X-RateLimit-Remaining(이번 1분 동안 남은 요청 수), X-RateLimit-Reset(다음 1분이 시작될 때까지 남은 초)이 들어 있습니다. 어느 한도든 넘으면 Retry-After 헤더와 함께 429 rate_limited를 받습니다. 그 초만큼 기다린 뒤 다시 시도하세요.
인물 공개에는 모든 플랜에 한도가 하나 더 있습니다. 계정은 1분에 최대 200명까지 공개할 수 있습니다. 이를 넘어도 429 rate_limited를 받습니다.
검색과 집계
검색, 집계, 미리보기는 무료입니다. 이 한도는 계정의 모든 키와 커넥터를 합쳐 계정 단위로 적용되므로, 키를 하나 더 만들어도 늘어나지 않습니다.
| 플랜 | 분당 | 일일 집계 | 일일 미리보기 행 |
|---|---|---|---|
| 플랜 없음, API 키 또는 CLI | 10 | 500 | 500 |
| 플랜 없음, AI 어시스턴트 | 20 | 1,000 | 1,000 |
| Starter | 30 | 제한 없음 | 제한 없음 |
| Pro | 60 | 제한 없음 | 제한 없음 |
| Scale | 90 | 제한 없음 | 제한 없음 |
| Hyperscale | 120 | 제한 없음 | 제한 없음 |
플랜이 없으면 검색과 집계 응답에 X-RateLimit-Daily-Limit과 X-RateLimit-Daily-Remaining도 들어 있습니다. 미리보기 한 번에는 최대 10명이 들어갑니다.
키별 일일 한도
플랜이 없으면 각 키에 일일 한도도 있습니다. 플랜이 있으면 일일 한도는 이메일 찾기에만 있고, 나머지는 크레딧으로 제한됩니다. 일일 한도는 UTC 자정에 초기화됩니다. GET /api/v1/account에서 오늘 남은 양을 볼 수 있습니다.
| 항목 | 하루 | 호출당 |
|---|---|---|
| 필터로 공개한 인물 | 100(플랜이 있으면 제한 없음) | 25 |
| 내보내기 행 | 50,000(플랜이 있으면 제한 없음) | 파일당 50,000, 배치당 500,000 |
| 이메일 찾기 조회 | 2,000 | 분당 30, 리스트는 최대 10,000행 |
플랜이 없는 계정은 하루에 새 이메일을 모두 합쳐 최대 10개까지 찾을 수 있습니다. 공개, 이메일 찾기 결과, 내보내기 행이 함께 집계되며, 이전에 이미 가지고 있던 이메일은 집계되지 않습니다.
일일 한도를 넘으면 429 daily_limit_reached를 받습니다. 일일 공개 한도보다 많은 인물이 필요하면 리스트로 저장하거나, 내보내거나, 캠페인에 추가하세요. 이 방법들은 수천 명을 다루도록 만들어졌습니다. 이메일 찾기는 고유한 코드로 응답합니다. finder_rate_limit(분당), finder_daily_limit(일일), finder_miss_rate_throttle(조회 대부분이 아무것도 찾지 못함)입니다.
페이지
모든 목록은 limit과 cursor를 받습니다. 응답은 고유한 키(예: campaigns나 people)를 유지하고 total, limit, offset, next_cursor, has_more를 추가합니다. 다음 페이지를 받으려면 next_cursor를 cursor로 넘기세요. 마지막 페이지에서는 null입니다. 행을 직접 세는 편이 좋다면 offset도 쓸 수 있습니다.
일부 목록은 일찍 끝나거나 고유한 방식으로 페이지를 나눕니다. 캠페인 안의 인물은 after를 next_after로 설정해 정해진 순서로 페이지를 넘기며, 이 페이지에는 next_cursor가 없습니다. 캠페인 답장도 after와 next_after로 같은 방식으로 페이지를 넘깁니다. 캠페인 목록은 처음 500개 캠페인까지 조회할 수 있고, cursor는 그 안에서 페이지를 넘깁니다. 받은편지함, 캠페인 답장, 캠페인 안의 인물은 ISO 8601 형식의 날짜 필터(updated_after와 received_after, 또는 created_after)도 받습니다.
curl "https://app.argorant.com/api/v1/campaigns?limit=25" -H "Authorization: Bearer $ARGORANT_API_KEY"
curl "https://app.argorant.com/api/v1/campaigns?limit=25&cursor=bzoyNQ" -H "Authorization: Bearer $ARGORANT_API_KEY"total_is_estimate가 true이면 total은 최소한 그만큼 있다는 뜻입니다. 예를 들어 리스트가 최대 크기에 도달한 경우입니다.
안전한 재시도
모든 쓰기 작업에 Idempotency-Key 헤더를 보내세요. 생성, 변경, 삭제, 답장, 전달, 그리고 크레딧이나 돈을 쓰는 모든 작업이 해당됩니다. 새 작업마다 새 무작위 값을 쓰고, 그 작업을 재시도할 때는 같은 값을 쓰세요.
- 24시간 안에 같은 키와 같은 본문을 보내면
Idempotent-Replayed: true헤더와 함께 첫 응답이 돌아옵니다. 아무것도 두 번 실행되지 않습니다. - 같은 키를 다른 본문과 함께 보내면
409 idempotency_conflict로 응답합니다. - 첫 요청이 아직 실행 중일 때 재시도하면
409 idempotency_in_progress로 응답합니다. 잠시 기다렸다가 다시 시도하세요. - 오류는 저장되지 않으므로, 문제를 고친 뒤 같은 키로 재시도할 수 있습니다.
curl -X POST "https://app.argorant.com/api/v1/exports" \
-H "Authorization: Bearer $ARGORANT_API_KEY" \
-H "Idempotency-Key: export-cfo-germany-2026-10-07" \
-H "Content-Type: application/json" \
-d '{"filters":{"title":"CFO","country":"Germany"},"limit":500}'시작할 수 없는 캠페인
POST /api/v1/campaigns/{id}/launch는 무언가 빠져 있는 동안 launch_blocked로 응답합니다. 예를 들어 이메일, 오늘 여유가 남은 메일함, 인물이 빠진 경우입니다. details.blockers에 빠진 항목이 하나씩 쉬운 말로 나옵니다. GET /api/v1/campaigns/{id}도 같은 목록을 launch_blockers로 보여 주므로, 시작하기 전에 고칠 수 있습니다.