ArgorantDocs

오류와 한도

하나로 통일된 오류 형식, 모든 오류 코드, 요청 ID, 플랜별 요청 한도, 검색과 집계의 한도, 일일 한도, 페이지, 안전한 재시도를 설명합니다.

하나로 통일된 오류 형식

모든 오류 응답은 같은 모양입니다. 무엇을 할지는 error.code를 읽고 판단하고, 사람에게는 error.message를 보여 주세요. 메시지는 쉬운 문장 하나입니다.

JSON
{
  "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_request400요청에 빠진 것이 있거나 값이 잘못되었습니다. 메시지에 고칠 부분이 나옵니다.
launch_blocked400캠페인을 아직 시작할 수 없습니다. details.blockers에 빠진 항목이 나옵니다.
unauthorized401API 키가 없거나, 키가 잘못되었거나 취소되었습니다.
api_key_required401이 경로에는 브라우저 세션이 아니라 API 키나 커넥터 로그인이 필요합니다.
plan_required402계정의 플랜에 이 기능이 포함되어 있지 않습니다. 메시지에 이 기능이 포함된 플랜이 나옵니다. 플랜도 크레딧도 없는 계정의 키는 모든 호출에서 이 코드를 받습니다.
insufficient_credits402이 호출에 필요한 크레딧이 부족합니다. details에 필요한 크레딧 수가 나옵니다. 비용은 청구되지 않았습니다.
scope_missing403키에 이 호출에 필요한 범위가 없습니다. 그 범위를 가진 키를 만드세요.
permission_missing403워크스페이스에서의 역할로는 이 작업을 할 수 없습니다.
forbidden403이 계정에는 허용되지 않는 작업입니다.
not_found404워크스페이스에 해당 항목이 없습니다. 다른 워크스페이스의 항목도 같은 방식으로 응답합니다.
route_not_found404해당 엔드포인트가 없습니다. 레퍼런스와 경로를 대조해 보세요.
method_not_allowed405경로는 있지만 이 HTTP 메서드로는 쓸 수 없습니다. details.allowed에 사용할 수 있는 메서드가 나옵니다.
conflict409항목이 이 작업을 허용하지 않는 상태입니다. 예를 들어 실행 중인 캠페인을 삭제하려는 경우입니다.
idempotency_conflict409이 Idempotency-Key는 이미 다른 본문과 함께 사용되었습니다.
idempotency_in_progress409이 Idempotency-Key를 사용한 요청이 아직 실행 중입니다. 기다렸다가 다시 시도하세요.
gone410항목이 만료되었습니다. 예를 들어 보관 기간이 지난 내보내기 파일입니다.
quote_expired410견적이 너무 오래되었습니다. 새 견적을 받고 다시 확인하세요.
validation_error422필드의 타입이 잘못되었거나 필드가 빠졌습니다. details.fields에 문제가 하나씩 나옵니다.
access_key_activation_required428초대받은 이 액세스 키는 아직 활성화되지 않았습니다. 먼저 details.claim_url에서 이메일을 확인하세요.
rate_limited429이번 1분 또는 10초 동안 요청이 너무 많았거나, 이번 1분 동안 검색과 집계가 너무 많았거나, 1분에 200명을 넘게 공개했습니다. Retry-After초만큼 기다리세요.
daily_limit_reached429일일 한도를 다 썼습니다. 이런 종류의 호출에 대한 키의 한도이거나, 플랜이 없는 계정의 하루 새 이메일 한도입니다. details.action에 어느 한도인지 나옵니다. UTC 자정에 초기화됩니다.
internal_error500저희 쪽에서 문제가 생겼습니다. 다시 시도하고, 계속 실패하면 요청 ID를 알려 주세요.
unavailable503서비스의 일부가 바쁘거나 일시정지되어 있습니다. 1분 뒤에 다시 시도하세요.
confirmation_required400주문에는 confirmed=true가 필요하며, 결제하는 사람이 승인한 뒤에만 보내야 합니다.
invalid_webhook_url400웹훅 주소는 공개된 https:// 주소여야 합니다.
invalid_webhook_events400알 수 없는 이벤트 이름이 있거나 이벤트가 지정되지 않았습니다. details.invalid에 알 수 없는 이름이 나옵니다.
webhook_limit_reached400켜져 있는 웹훅이 10개이거나, 꺼진 것을 포함해 모두 50개입니다. 먼저 하나를 삭제하거나 끄세요. 팀 멤버마다 따로 가집니다.
event_not_subscribed400테스트 호출에 웹훅이 받지 않는 이벤트를 지정했습니다. details.events에 웹훅이 받는 이벤트가 나옵니다.
company_credits_required402전체 기업 프로필에는 크레딧이 들며 계정의 크레딧이 부족합니다. details.teaser에 무료 부분이 들어 있고, 비용은 청구되지 않았습니다.
search_busy503지금 검색이 바쁩니다. 몇 초 뒤에 다시 시도하세요.
phones_not_in_plan402전화번호는 Pro 플랜부터 제공됩니다. 비용은 청구되지 않았습니다.
card_not_charged402저장된 카드로 결제되지 않았습니다. 구매된 것은 없으니 결제 링크로 결제하세요.
owner_only403워크스페이스 소유주만 할 수 있는 작업입니다. 예를 들어 메일함 주문이나 해지입니다.
quote_not_found404견적이 없거나 다른 사람의 것입니다. 새 견적을 받으세요.
charge_in_progress409지금 이 견적이 결제되는 중입니다. 잠시 뒤 주문을 확인하세요.
not_enough_names409사용 가능한 도메인 이름을 충분히 찾지 못했습니다. 도메인을 직접 몇 개 보내 주세요.
not_paid409주문이 아직 결제되지 않아서 해지할 것이 없습니다.
reason_required422메일함을 해지하려면 제시된 선택지 중에서 사유를 골라야 합니다.
not_connected409그 도구가 아직 연결되지 않았습니다. 먼저 설정의 연결된 도구에서 연결하세요.
unsupported_tool409이 연결된 도구는 인물을 직접 받을 수 없습니다. 대신 내보내기 페이지에서 내보내기를 보내세요.
tool_key_rejected409연결된 도구가 저장된 키를 받아들이지 않았습니다. 설정의 연결된 도구에서 다시 연결하세요.
price_mismatch409상대에게 보여 준 가격이 견적 가격과 다릅니다. 견적 가격을 보여 주고 다시 물어보세요.
quote_other_session409견적이 다른 키나 연결로 만들어졌습니다. 여기서 새 견적을 요청하고 다시 확인하세요.
export_failed409내보내기가 끝나지 않아서 보낼 것이 없습니다. 내보내기를 다시 실행하세요.
sign_in_failed422메일 서버가 로그인을 받아들이지 않아 메일함이 연결되지 않았습니다. details.test에 발송과 답장 읽기 각각에서 무엇이 잘못되었는지 나옵니다.
campaign_not_started409캠페인이 초안이라서 일시정지할 것이 없습니다. 먼저 시작하세요.
finder_rate_limit429이번 1분 동안 이메일 찾기 단건 조회가 30회를 넘었습니다. Retry-After초만큼 기다리세요.
finder_daily_limit429오늘 이메일 찾기 조회가 2,000회에 도달했습니다. UTC 자정에 초기화됩니다.
finder_miss_rate_throttle429최근 조회 대부분이 아무것도 찾지 못해서, 한동안 조회 속도가 시간당 20회로 낮춰집니다. 이름과 도메인을 확인하세요.

일부 작업에는 confirmation_required나 quote_not_found처럼 고유한 코드가 더 있습니다. 각 작업의 코드는 레퍼런스에 나와 있습니다. 모르는 코드는 HTTP 상태에 따라 처리하세요.

요청 ID

모든 응답에는 X-Request-Id 헤더가 있고, 모든 오류는 이 값을 request_id로 다시 담습니다. 내 로그에서 호출을 찾으려면 X-Request-Id 헤더에 직접 정한 ID(영문자, 숫자, 점, 하이픈, 밑줄로 8~64자)를 보내세요. 도움을 요청할 때 이 ID를 알려 주세요.

분당 요청 수

각 키는 1분에 다음 수만큼 요청을 보낼 수 있고, 10초 동안에는 두 번째 숫자까지 보낼 수 있습니다.

플랜분당 요청 수10초 동안
플랜 없음, API 키 또는 CLI3015
플랜 없음, AI 어시스턴트6020
Starter6015
Pro24060
Scale600150
Hyperscale1,200300

플랜 없음은 아직 플랜을 고르지 않은 계정의 처음 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 키 또는 CLI10500500
플랜 없음, AI 어시스턴트201,0001,000
Starter30제한 없음제한 없음
Pro60제한 없음제한 없음
Scale90제한 없음제한 없음
Hyperscale120제한 없음제한 없음

플랜이 없으면 검색과 집계 응답에 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)도 받습니다.

Shell
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로 응답합니다. 잠시 기다렸다가 다시 시도하세요.
  • 오류는 저장되지 않으므로, 문제를 고친 뒤 같은 키로 재시도할 수 있습니다.
Shell
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로 보여 주므로, 시작하기 전에 고칠 수 있습니다.

이 페이지의 내용