속도 제한, 오류, 결제
이 페이지는 연동을 멈추게 하는 세 가지, 즉 요청 소진, 오류 응답, 크레딧 소진에 대한 레퍼런스입니다. 또한 이 세 가지를 계정에서 어디서 지켜볼 수 있는지도 보여줍니다.
어제까지 잘 되던 호출이 알 수 없는 코드를 반환할 때, 앱이 얼마나 많은 요청을 할 수 있는지 가늠할 때, 또는 출시 전에 호출 비용을 정확히 알고 싶을 때 이 페이지를 찾으세요.
속도 제한
한도는 접근 모드에 따라 키별로 설정됩니다:
| 접근 모드 | 한도 |
|---|---|
| 라이브 유료: basic (모든 새 라이브 키의 기본값) | 시간당 1,000 요청 |
| 라이브 유료: premium (관리자 지정) | 시간당 5,000 요청 |
| 라이브 유료: pro (관리자 지정) | 시간당 15,000 요청 |
| partner 또는 enterprise | 관리자 설정 |
모든 cogv_test_ 샌드박스 키 | 시간당 25 요청, 일 100 요청, 초당 1 요청 |
유효한 키로 접근하는 메타데이터 영역(health, me, discover) | 시간당 60 요청, 초당 1 요청 |
새 라이브 키는 승인 단계 없이 basic에서 시작합니다. Premium과 pro는 Cognivo가 지정하며, partner와 enterprise 한도는 계약에 따라 설정됩니다. 표준 RateLimit-* 헤더가 모든 호출에 함께 돌아오므로 남은 예산을 추측하지 않고 확인할 수 있습니다. 예산이 소진되면 429 rate_limited와 함께 언제 다시 시도할지 알려주는 Retry-After 헤더가 반환됩니다.
사용량 지켜보기
dApp에 로그인해 왼쪽 사이드바에서 Account를 열고 Developers를 선택한 뒤 Usage 탭을 여세요.
상단의 기간 선택기로 Last 24 hours, Last 7 days, Last 30 days를 전환합니다. 그 옆에는 크레딧 잔액을 보여주는 칩과, 여러분의 키에 적용되는 속도 등급 및 시간당 한도를 보여주는 칩이 있습니다. 그 아래에는 다섯 개의 카운터가 해당 기간을 Requests, Successful, Errors, Rate limited, Credits used로 나누어 보여주고, Outcome breakdown 카드가 같은 기간을 세 갈래로 분해합니다.
Quoted vs charged는 청구 금액을 걱정하기 전에 읽어야 할 패널입니다. 제품 자체의 표현을 빌리면 "Quoted is the list price. Charged is what actually came out of your balance."입니다. 두 숫자가 항상 같지는 않습니다. 실패한 호출, 거부된 호출, 정직하게 비어 있는 답변은 견적은 되지만 절대 과금되지 않기 때문입니다.
Request history는 개별 호출을 나열하며 키, 엔드포인트, 상태로 필터링할 수 있습니다. 두 가지 빈 상태는 서로 다른 의미입니다. "No requests match these filters."는 이 기간에 호출은 있지만 여러분이 지정한 필터와 일치하는 것이 없다는 뜻이므로 필터를 넓히세요. "No usage in this window yet."는 이 기간에 어떤 키의 호출도 전혀 들어오지 않았다는 뜻입니다. 둘 다 오류가 아니며, 둘 다 호출이 유실되었다는 뜻이 아닙니다. 트래픽이 있을 것으로 예상했는데 0이 보인다면, 앱이 여러분이 생각하는 그 키를 쓰고 있는지 확인하고 기간을 넓혀 보세요.
오류 코드
| HTTP | error | 의미 |
|---|---|---|
| 400 | bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token | 잘못된 형식의 입력입니다. chain은 eth, base, bsc 중 하나여야 하며, 주소는 0x 뒤에 16진수 40자여야 합니다. |
| 401 | missing_api_key | X-API-Key나 Bearer 토큰이 제시되지 않았습니다. |
| 401 | invalid_api_key | 알 수 없는 키이거나 Cognivo v2 키가 아닙니다. |
| 402 | payment_required | 이 호출을 위한 Cognivo 크레딧이 부족합니다. 아무것도 과금되지 않았습니다. |
| 403 | access_required | 메타데이터 전용의 레거시 키가 라이브 호출을 시도했습니다. |
| 403 | sandbox_limited | 샌드박스(cogv_test_) 키가 라이브 인텔리전스 호출을 시도했습니다. |
| 403 | trial_expired | 키의 선택적 트라이얼 허용량이 만료되었습니다. |
| 403 | trial_exhausted | 키의 선택적 트라이얼 허용량을 모두 사용했습니다. |
| 403 | endpoint_denied | 키의 접근 계약이 이 엔드포인트를 포함하지 않습니다. |
| 403 | chain_denied | 키가 특정 네트워크로 제한되어 있는데 이 요청은 다른 네트워크를 지정했습니다. 상위 호출 이전, 그리고 허용량이 사용되기 이전에 거부됩니다. |
| 403 | key_expired | 키의 만료일이 지났습니다. GET /v1/api/me를 포함해 모든 곳에서 거부됩니다. |
| 403 | suspended_key | 키가 정지되어 실행할 수 없습니다. 포털에 그 이유가 표시됩니다. |
| 403 | revoked_api_key | 키가 폐기되었거나 로테이션으로 교체되었습니다. |
| 403 | project_disabled | 소유 프로젝트가 정지되었거나 보관 처리되었습니다. |
| 403 | scope_denied | 이 엔드포인트에 필요한 스코프를 키가 갖고 있지 않습니다. |
| 403 | origin_denied | 키에 Origin 또는 IP 허용 목록이 설정되어 있는데 이 요청이 일치하지 않았습니다. |
| 404 | public_api_disabled | 공개 API가 일시적으로 꺼져 있습니다. |
| 422 | insufficient_data 및 유사 항목 | 도구는 실행되었지만 공정한 결과의 근거를 확보하지 못했습니다. 과금되지 않습니다. |
| 429 | rate_limited | 요청 예산이 소진되었습니다. 응답에 Retry-After가 함께 옵니다. |
| 500 | internal_error | 예기치 못한 실패입니다. 지원팀에 연락할 때 request_id를 포함하세요. |
| 503 | pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable | 드물게 발생하는 결제 또는 의존성 문제입니다. 아무것도 과금되지 않았으므로 다시 시도하세요. |
모든 응답에는 request_id가 들어 있고, 성공한 응답은 이를 meta.request_id로 한 번 더 담습니다. 보관해 두세요. 지원팀은 그 값 하나로 개별 호출을 추적할 수 있습니다.
흔한 오류와 해결 방법
- 401
missing_api_key. 키가 저희에게 도달하지 않았습니다.X-API-Key헤더에 정확한 철자로 보내거나Authorization: Bearer YOUR_API_KEY로 보내고, 프록시가 헤더를 제거하고 있지 않은지 확인하세요. - 401
invalid_api_key. 키는cogv_live_또는cogv_test_로 시작해야 합니다. 앞뒤 공백 없이 키 전체를 복사하세요. 원본을 잃어버렸다면 포털에서 키를 로테이션하고 새 키를 사용하세요. - 402
payment_required. Cognivo 결제 페이지에서 충전한 뒤 다시 시도하세요. 아무것도 과금되지 않았습니다.GET /v1/api/me가 현재 잔액을 보여줍니다. - 403
revoked_api_key. 포털에서 최신 키를 가져오세요. 기존 키는 다시는 작동하지 않습니다. - 403
scope_denied. 키 자체는 유효하지만 이 엔드포인트에 필요한 스코프가 없습니다. 예를 들어wallet/approvals에는security:read가 필요합니다. 인증과 API 키를 참고하세요. - 403
origin_denied. 허용 목록에 있는 origin이나 IP에서 호출하거나, 키의 목록을 비우세요. - 403
access_required. 셀프 서비스 결제 이전에 만들어진 메타데이터 전용 레거시 키입니다. 포털에서 새 라이브 키를 만드세요. - 403
sandbox_limited. 샌드박스 키는 테스트용이며 라이브 인텔리전스를 실행할 수 없습니다. 라이브 키를 만드세요. - 403
chain_denied.GET /v1/api/me에서allowed_chains를 확인하세요. 거기서null은 제한이 없다는 뜻입니다. 아무것도 과금되지 않았습니다. - 403
trial_expired또는trial_exhausted. 선택적 평가 허용량이 끝났습니다. 트라이얼이 꼭 필요한 것은 아니므로 일반 라이브 키로 전환하세요. - 403
endpoint_denied. 여러분의 계약은 다른 엔드포인트를 포함하지만 이 엔드포인트는 포함하지 않습니다. 포함해 달라고 요청하세요. - 403
suspended_key. 포털에 그 이유가 표시됩니다. 이유가 불명확하다면request_id와 함께 dApp에서 지원팀에 문의하세요. - 429
rate_limited.Retry-After헤더를 지키고 백오프가 있는 클라이언트 측 큐를 추가하거나, 더 높은 한도를 문의하세요. - 400
invalid_chain.eth,base,bsc를 사용하세요.ethereum같은 이름이나 숫자 체인 id는 허용되지 않습니다. - 400
invalid_address,invalid_wallet,invalid_token.0x뒤에 16진수 40자로 이루어진 전체 주소를 보내세요. API는 ENS 이름이나 토큰 심볼을 해석하지 않습니다. - 422
insufficient_data. 장애도 아니고 여러분의 잘못도 아닙니다. 도구는 실행되었지만 공정한 답의 근거를 확보하지 못했습니다. 예를 들어 해당 토큰에 가격이 매겨진 거래가 없는 지갑에wallet/pnl을 호출한 경우입니다. 답이 0이라는 뜻이 아니라 Cognivo가 답을 검증할 수 없었다는 뜻입니다. 422에는 절대 과금되지 않습니다. - 404
public_api_disabled. 공개 API가 일시적으로 꺼져 있습니다. URL이 틀린 것이 아니므로 나중에 다시 시도하세요.
크레딧과 결제
라이브 키는 셀프 서비스입니다. 신청도 구독도 없습니다. 새 라이브 키는 즉시 작동하며, 성공한 호출마다 해당 엔드포인트의 크레딧 가격이 프로젝트 소유자의 Cognivo 크레딧 잔액에서 차감됩니다. 채팅과 dApp이 쓰는 것과 동일한 크레딧입니다. 모든 계정은 매일 5 무료 크레딧을 받으며, UTC 자정에 초기화됩니다. 현재 Developer API 호출에 대한 과금은 꺼져 있어, 호출이 성공해도 아무것도 차감되지 않고 잔액도 변하지 않습니다.
각 엔드포인트의 크레딧 가격은 Developers 페이지의 Endpoints 탭에서 엔드포인트 옆에 표시되며, 무료 엔드포인트는 그곳에 Free로 표시됩니다. 가격은 하드코딩하지 말고 포털에서 읽으세요.
- 실패한 호출에는 절대 과금되지 않습니다. 오류, 타임아웃, 거부된 호출, 속도 제한에는 비용이 들지 않습니다.
- 성공한 호출은 정확히 한 번만 과금되므로 재시도는 안전합니다.
- 정직하게 비어 있는 결과는 무료입니다. 422와 비어 있는
wallet/approvals목록은 유효한 답이며 과금되지 않습니다. - 크레딧 부족은
402 payment_required를 반환하며 아무것도 과금되지 않습니다. dApp에서 충전한 뒤 다시 시도하세요. - 샌드박스(
cogv_test_) 키는 절대 과금되지 않으며 라이브 인텔리전스를 실행할 수 없습니다. - 정지된 키와 비활성화된 프로젝트는 아무것도 실행할 수 없으며 절대 과금되지 않습니다.
- Enterprise는 맞춤 요금, 맞춤 한도, 대량 사용을 위한 요청 경로이며 dApp에서 요청합니다.
결과를 정직하게 읽기
API 결과는 Cognivo가 무엇을 확인했고 온체인에서 무엇을 발견했는지를 설명합니다. 깨끗한 결과는 토큰이나 지갑이 안전하다는 증거가 아니며, 플래그가 붙은 결과는 사기의 증거가 아닙니다. 값이 없거나 이용 불가인 필드는 그 항목을 Cognivo가 검증하지 못했다는 뜻이지 아무것도 없다는 뜻이 아닙니다. 모든 응답을 여러분 자신의 리서치를 위한 하나의 입력으로 다루세요.
다음 단계
매개변수, 스코프, 예제 응답은 엔드포인트 레퍼런스에서 찾아보고, 인증과 API 키로 키를 더 엄격하게 조이거나, 제품 전반에서 크레딧이 어떻게 동작하는지는 결제와 크레딧에서 확인하세요.