Giới hạn tốc độ, lỗi và tính phí
Giới hạn tốc độ
Giới hạn tính theo từng key, theo chế độ truy cập:
| Chế độ truy cập | Giới hạn |
|---|---|
free (metadata: health, me, discover) | 60 yêu cầu/giờ, với trần bùng nổ 1/giây |
| basic (trả phí, khi kích hoạt) | 1,000 yêu cầu/giờ |
| premium (trả phí, khi kích hoạt) | 5,000 yêu cầu/giờ |
| pro (trả phí, khi kích hoạt) | 15,000 yêu cầu/giờ |
| partner / enterprise | do quản trị viên cấu hình |
bất kỳ key sandbox cogv_test_ nào | 25 yêu cầu/giờ và 100/ngày |
Key mới bắt đầu chỉ với quyền truy cập metadata free. Quyền truy cập dùng thử (trial) do quản trị viên cấp, có giới hạn và sẽ hết hạn; giới hạn partner và enterprise được cấu hình theo thỏa thuận - hãy yêu cầu quyền truy cập từ dApp. Các header RateLimit-* chuẩn được trả về; khi hết hạn mức, bạn nhận 429 rate_limited.
Mã lỗi
| HTTP | error | Ý nghĩa |
|---|---|---|
| 400 | bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token | đầu vào sai định dạng; chain phải là eth, base hoặc bsc; địa chỉ phải là 0x + 40 ký tự hex |
| 401 | missing_api_key | không có X-API-Key (hoặc Bearer) nào được gửi |
| 401 | invalid_api_key | key không được nhận diện hoặc không phải key Cognivo v2 |
| 402 | insufficient_credits | sử dụng trả phí: số dư tín dụng Cognivo của bạn không đủ cho lệnh gọi (chưa có gì bị tính phí) |
| 402 | payment_required | endpoint này cần quyền truy cập trả phí trên key này và không có phương thức thanh toán hợp lệ nào bao phủ lệnh gọi (chưa có gì bị tính phí) |
| 403 | access_required | key không có quyền truy cập các endpoint trí tuệ trực tiếp - hãy yêu cầu quyền truy cập trial, partner, trả phí hoặc enterprise |
| 403 | sandbox_limited | một key sandbox (cogv_test_) thử một lệnh gọi trực tiếp ngoài hạn mức demo được quản trị viên bật |
| 403 | trial_expired | quyền truy cập dùng thử của key đã hết hạn |
| 403 | trial_exhausted | hạn mức dùng thử của key đã dùng hết |
| 403 | endpoint_denied | quyền truy cập của key không bao gồm endpoint cụ thể này |
| 403 | suspended_key | key đã bị quản trị viên đình chỉ |
| 403 | revoked_api_key | key đã bị thu hồi hoặc đã bị xoay vòng bỏ đi |
| 403 | project_disabled | dự án sở hữu key bị đình chỉ hoặc lưu trữ |
| 403 | scope_denied | key thiếu scope mà endpoint này cần |
| 403 | origin_denied | key có cấu hình danh sách cho phép Origin/IP và yêu cầu không khớp |
| 404 | public_api_disabled | API công khai tạm thời bị tắt |
| 422 | insufficient_data (và tương tự) | công cụ đã chạy nhưng không thể đưa ra kết quả có căn cứ công bằng - bạn không bị tính phí |
| 429 | rate_limited | hạn mức theo giờ đã cạn |
| 500 | internal_error | lỗi không mong đợi - hãy kèm request_id khi liên hệ hỗ trợ |
| 503 | billing_unavailable / unavailable | sự cố tạm thời của thành phần phụ thuộc - thử lại sau, không có gì bị tính phí |
Mọi phản hồi đều mang request_id (và meta.request_id khi thành công). Hãy giữ lại; đội hỗ trợ có thể truy vết một lệnh gọi từ nó.
Các lỗi thường gặp và cách khắc phục
- 401
missing_api_key- key chưa bao giờ đến được chúng tôi. Gửi nó trong headerX-API-Key(đúng tên) hoặc dưới dạngAuthorization: Bearer YOUR_API_KEY, và kiểm tra xem proxy hay framework có đang loại bỏ header không. - 401
invalid_api_key- key không được nhận diện. Nó phải bắt đầu bằngcogv_live_hoặccogv_test_; kiểm tra bạn đã sao chép toàn bộ key và không có khoảng trắng thừa. Nếu bạn làm mất bản gốc, hãy xoay vòng key trong cổng nhà phát triển và dùng key mới. - 403
revoked_api_key- key này đã bị thu hồi hoặc bị xoay vòng bỏ đi. Lấy key mới nhất từ cổng nhà phát triển; key cũ sẽ không bao giờ hoạt động lại. - 403
scope_denied- key hoạt động, nhưng thiếu scope mà endpoint này cần (ví dụsecurity:readchowallet/approvals). Chỉnh sửa scope của key hoặc tạo key mới với scope phù hợp; xem Xác thực và API key. - 403
origin_denied- key có danh sách cho phép Origin hoặc IP và yêu cầu này đến từ nơi khác. Gọi từ một origin/IP nằm trong danh sách cho phép, hoặc xóa các danh sách trên key. - 403
access_required- key hợp lệ nhưng không có quyền truy cập các endpoint trí tuệ trực tiếp. Yêu cầu quyền truy cập trial, partner, trả phí hoặc enterprise từ cổng nhà phát triển; không có nó, lệnh gọi không bao giờ chạy (và không bao giờ tính phí). - 403
sandbox_limited- một key sandbox (cogv_test_) thử một lệnh gọi trí tuệ trực tiếp ngoài hạn mức demo của nó. Hãy nhờ quản trị viên bật hạn mức live-demo cho key, hoặc dùng live key có quyền truy cập. - 403
trial_expired/trial_exhausted- bản dùng thử của bạn đã kết thúc (hết thời gian hoặc hết hạn mức). Yêu cầu gia hạn hoặc chuyển sang quyền truy cập trả phí, partner hoặc enterprise. - 403
endpoint_denied- quyền truy cập của bạn bao gồm các endpoint khác nhưng không có endpoint này (quyền truy cập theo từng endpoint phổ biến ở các cấp partner/enterprise). Hãy yêu cầu quyền truy cập endpoint này. - 403
suspended_key- key đã bị quản trị viên đình chỉ. Liên hệ hỗ trợ từ dApp kèmrequest_idcủa bạn. - 402
payment_required- lệnh gọi này cần quyền truy cập trả phí trên key này. Nạp thêm tín dụng Cognivo hoặc yêu cầu chế độ truy cập bao phủ endpoint đó; chưa có gì bị tính phí. - 429
rate_limited- bạn đã dùng hết hạn mức của key này. Giảm tốc độ, thêm hàng đợi phía client với backoff, hoặc yêu cầu chế độ truy cập cao hơn. Lưu ý key sandboxcogv_test_bị giới hạn 25 yêu cầu/giờ và 100/ngày; quyền truy cập metadata free bị giới hạn 60/giờ với trần bùng nổ 1/giây. - 400
invalid_chain-chainphải làeth,basehoặcbsc. Các tên nhưethereumhoặc chain id dạng số như8453không được chấp nhận. - 400
invalid_address/invalid_wallet/invalid_token- gửi địa chỉ đầy đủ dạng0x+ 40 ký tự hex. API không phân giải tên ENS hay ký hiệu token. - 422
insufficient_data- không phải sự cố và không phải lỗi của bạn: công cụ đã chạy nhưng không thể đưa ra câu trả lời có căn cứ công bằng (ví dụwallet/pnltrên một ví không có giao dịch được định giá với token đó). Bạn không bao giờ bị tính phí cho một 422; hãy thử ví/token khác hoặc một câu hỏi rộng hơn. - 404
public_api_disabled- API công khai tạm thời bị tắt, không phải sai URL. Thử lại sau hoặc kiểm tra kênh thông báo.
Quyền truy cập, tính phí và tín dụng
Developer API được kiểm soát truy cập trong giai đoạn truy cập sớm. Một key free có thể khám phá: đọc tài liệu, gọi GET /v1/api/health, tự kiểm tra qua GET /v1/api/me, và thực hiện các lệnh gọi sandbox/demo có giới hạn. Các endpoint trí tuệ trực tiếp cần quyền truy cập trial, partner, trả phí hoặc enterprise; không có nó, chúng trả về lỗi rõ ràng (access_required, trial_expired, payment_required và tương tự) thay vì chạy miễn phí.
- Sử dụng trả phí được tính bằng tín dụng Cognivo cho mỗi lệnh gọi thành công, trừ từ số dư tín dụng Cognivo hiện có của bạn (cùng loại tín dụng với Chat/Telegram), do tài khoản của chủ dự án chi trả. Thất bại, hết thời gian chờ, kết quả rỗng và lỗi không bị tính phí.
- Việc tính phí có tính idempotent - một yêu cầu được thử lại hoặc bị trùng lặp không thể bị tính phí hai lần.
- Key sandbox (
cogv_test_) dành cho kiểm thử tích hợp: giới hạn 25 yêu cầu/giờ và 100/ngày, và chỉ có thể chạy một hạn mức live-demo nhỏ khi được quản trị viên bật. - Quyền truy cập dùng thử (trial) do quản trị viên cấp, có giới hạn và sẽ hết hạn.
- Enterprise là gói tùy chỉnh: giá, giới hạn cao hơn và quyền truy cập theo từng endpoint - hãy yêu cầu quyền truy cập từ dApp.
Chi phí tín dụng theo từng endpoint (áp dụng cho sử dụng trả phí; công bố để minh bạch):
| Endpoint | Tín dụng mỗi lệnh gọi thành công |
|---|---|
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 | miễn phí |
discover | miễn phí, với giới hạn tốc độ chặt |
Không phải lời khuyên tài chính
Kết quả API là các tín hiệu trí tuệ on-chain, không phải lời khuyên đầu tư, và việc không có red flag không phải là bằng chứng an toàn. Hãy luôn tự nghiên cứu.