속도 제한, 오류 및 과금
속도 제한
제한은 키별, 접근 모드별로 적용됩니다:
| 접근 모드 | 제한 |
|---|---|
free (메타데이터: health, me, discover) | 시간당 60 요청, 초당 1 버스트 상한 |
| basic (유료, 출시 후) | 시간당 1,000 요청 |
| premium (유료, 출시 후) | 시간당 5,000 요청 |
| pro (유료, 출시 후) | 시간당 15,000 요청 |
| partner / enterprise | 관리자 설정 |
모든 cogv_test_ 샌드박스 키 | 시간당 25 요청, 일 100 요청 |
새 키는 무료 메타데이터 접근만으로 시작합니다. 트라이얼 접근은 관리자가 부여하며 제한적이고 만료됩니다. 파트너와 엔터프라이즈 한도는 계약별로 설정됩니다. dApp에서 접근을 요청하세요. 표준 RateLimit-* 헤더가 반환되며, 소진 시 429 rate_limited를 받게 됩니다.
오류 코드
| 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 | insufficient_credits | 유료 사용: Cognivo 크레딧 잔액이 호출 비용을 감당할 수 없음 (아무것도 과금되지 않음) |
| 402 | payment_required | 이 엔드포인트는 이 키에서 유료 접근이 필요하며, 호출을 감당할 유효한 결제 경로가 없음 (아무것도 과금되지 않음) |
| 403 | access_required | 키에 라이브 인텔리전스 엔드포인트에 대한 접근 권한이 없음 - 트라이얼, 파트너, 유료 또는 엔터프라이즈 접근을 요청하세요 |
| 403 | sandbox_limited | 샌드박스(cogv_test_) 키가 관리자가 활성화한 데모 허용량 밖에서 라이브 호출을 시도함 |
| 403 | trial_expired | 키의 트라이얼 접근이 만료됨 |
| 403 | trial_exhausted | 키의 트라이얼 허용량이 모두 소진됨 |
| 403 | endpoint_denied | 키의 접근 권한이 이 특정 엔드포인트를 포함하지 않음 |
| 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 | 시간당 티어 예산 소진 |
| 500 | internal_error | 예기치 못한 실패 - 지원팀에 문의할 때 request_id를 포함하세요 |
| 503 | billing_unavailable / 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_로 시작해야 하며, 앞뒤 공백 없이 키 전체를 복사했는지 확인하세요. 원본을 잃어버렸다면 포털에서 키를 로테이션하고 새 키를 사용하세요. - 403
revoked_api_key- 이 키는 폐기되었거나 로테이션으로 교체되었습니다. 포털에서 최신 키를 가져오세요. 이전 키는 다시는 작동하지 않습니다. - 403
scope_denied- 키는 유효하지만 이 엔드포인트에 필요한 스코프(예:wallet/approvals에는security:read)가 없습니다. 키의 스코프를 수정하거나 올바른 스코프를 가진 키를 만드세요. 인증 및 API 키를 참고하세요. - 403
origin_denied- 키에 Origin 또는 IP 허용 목록이 있는데 이 요청은 다른 곳에서 왔습니다. 허용 목록에 있는 오리진/IP에서 호출하거나 키의 목록을 비우세요. - 403
access_required- 키는 유효하지만 라이브 인텔리전스 엔드포인트에 대한 접근 권한이 없습니다. Developer 포털에서 트라이얼, 파트너, 유료 또는 엔터프라이즈 접근을 요청하세요. 접근 권한 없이는 호출이 절대 실행되지 않습니다 (과금도 되지 않습니다). - 403
sandbox_limited- 샌드박스(cogv_test_) 키가 데모 허용량 밖에서 라이브 인텔리전스 호출을 시도했습니다. 관리자에게 키의 라이브 데모 허용량 활성화를 요청하거나, 접근 권한이 있는 라이브 키를 사용하세요. - 403
trial_expired/trial_exhausted- 트라이얼이 끝났습니다 (기간 또는 허용량). 연장을 요청하거나 유료, 파트너 또는 엔터프라이즈 접근으로 전환하세요. - 403
endpoint_denied- 접근 권한이 다른 엔드포인트는 포함하지만 이 엔드포인트는 포함하지 않습니다 (엔드포인트별 접근은 파트너/엔터프라이즈 부여에서 흔합니다). 이 엔드포인트에 대한 접근을 요청하세요. - 403
suspended_key- 관리자가 키를 정지했습니다.request_id와 함께 dApp에서 지원팀에 문의하세요. - 402
payment_required- 이 호출에는 이 키에서의 유료 접근이 필요합니다. Cognivo 크레딧을 충전하거나 이 엔드포인트를 포함하는 접근 모드를 요청하세요. 아무것도 과금되지 않았습니다. - 429
rate_limited- 이 키의 예산을 다 썼습니다. 속도를 늦추거나, 백오프가 있는 클라이언트 측 큐잉을 추가하거나, 더 높은 접근 모드를 요청하세요.cogv_test_샌드박스 키는 시간당 25 요청, 일 100 요청으로 제한되고, 무료 메타데이터 접근은 시간당 60 요청(초당 1 버스트 상한)으로 제한된다는 점을 기억하세요. - 400
invalid_chain-chain은eth,base,bsc중 하나여야 합니다.ethereum같은 이름이나8453같은 숫자 체인 ID는 허용되지 않습니다. - 400
invalid_address/invalid_wallet/invalid_token-0x+ 16진수 40자의 전체 주소를 보내세요. ENS 이름과 토큰 심볼은 API에서 해석되지 않습니다. - 422
insufficient_data- 장애도 아니고 여러분 잘못도 아닙니다. 도구는 실행되었지만 공정한 답의 근거를 확보하지 못한 것입니다 (예: 해당 토큰의 가격이 매겨진 거래가 없는 지갑에 대한wallet/pnl). 422에는 절대 과금되지 않습니다. 다른 지갑/토큰이나 더 넓은 질문을 시도해 보세요. - 404
public_api_disabled- 공개 API가 일시적으로 꺼져 있는 것이지 URL이 틀린 게 아닙니다. 나중에 다시 시도하거나 공지 채널을 확인하세요.
접근, 과금, 크레딧
Developer API는 얼리 액세스 기간 동안 접근이 제어됩니다. 무료 키도 탐색은 가능합니다: 문서 읽기, GET /v1/api/health 호출, GET /v1/api/me로 자기 자신 조회, 제한적인 샌드박스/데모 호출. 라이브 인텔리전스 엔드포인트에는 트라이얼, 파트너, 유료 또는 엔터프라이즈 접근이 필요합니다. 접근 권한이 없으면 무료로 실행되는 대신 명확한 오류(access_required, trial_expired, payment_required 등)가 반환됩니다.
- 유료 사용은 성공한 호출당 기존 Cognivo 크레딧 잔액(Chat/Telegram과 동일한 크레딧)에서 과금되며, 프로젝트 소유자 계정에서 차감됩니다. 실패, 타임아웃, 빈 결과, 오류에는 과금되지 않습니다.
- 과금은 멱등적입니다. 재시도되거나 중복된 요청이 이중 과금될 수 없습니다.
- 샌드박스(
cogv_test_) 키는 통합 테스트용입니다: 시간당 25 요청, 일 100 요청으로 제한되며, 관리자가 활성화한 경우에만 소량의 라이브 데모 허용량을 실행할 수 있습니다. - 트라이얼 접근은 관리자가 부여하며, 제한적이고 만료됩니다.
- 엔터프라이즈는 맞춤형입니다: 요금, 더 높은 한도, 엔드포인트별 접근. dApp에서 접근을 요청하세요.
엔드포인트별 크레딧 비용 (유료 사용에 적용되며, 투명성을 위해 공개합니다):
| 엔드포인트 | 성공한 호출당 크레딧 |
|---|---|
intel/liquidity | 2 |
intel/risk | 2 |
wallet/approvals | 2 |
intel/why-down | 3 |
intel/team-wallets | 5 |
wallet/exact-movements | 5 |
wallet/pnl | 10 |
health, me | 무료 |
discover | 무료 (엄격한 속도 상한 적용) |
투자 조언이 아닙니다
API 결과는 온체인 인텔리전스 신호이지 투자 조언이 아니며, 레드 플래그가 없다고 해서 안전이 증명되는 것은 아닙니다. 항상 스스로 조사하세요.