Giới hạn tốc độ, lỗi và tính phí

Trang này là tài liệu tham chiếu cho ba thứ khiến một tích hợp ngừng hoạt động: hết lượt yêu cầu, nhận về một lỗi, và hết tín dụng. Nó cũng cho biết bạn theo dõi cả ba từ đâu trong tài khoản của mình.

Hãy tìm tới trang này khi một lệnh gọi hôm qua còn chạy nay lại trả về một mã bạn không nhận ra, khi bạn đang ước lượng ứng dụng của mình có thể thực hiện bao nhiêu yêu cầu, hoặc khi bạn muốn biết chính xác một lệnh gọi sẽ tốn bao nhiêu trước khi phát hành.

Giới hạn tốc độ

Giới hạn được đặt theo từng key, theo chế độ truy cập:

Chế độ truy cập	Giới hạn
live trả phí: basic (mặc định cho mọi live key mới)	1,000 yêu cầu/giờ
live trả phí: premium (do quản trị viên cấp)	5,000 yêu cầu/giờ
live trả phí: pro (do quản trị viên cấp)	15,000 yêu cầu/giờ
partner hoặc 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ờ, 100/ngày, 1/giây
bề mặt siêu dữ liệu (health, me, discover) với bất kỳ key hợp lệ nào	60 yêu cầu/giờ, 1/giây

Một live key mới bắt đầu ở basic mà không cần bước phê duyệt nào. Premium và pro do Cognivo cấp, còn giới hạn partner và enterprise được đặt theo từng thỏa thuận. Các header RateLimit-* tiêu chuẩn trả về trên mọi lệnh gọi, nên bạn thấy được hạn mức còn lại mà không phải đoán. Khi hạn mức cạn, bạn nhận 429 rate_limited kèm header Retry-After cho biết khi nào nên thử lại.

Theo dõi mức sử dụng của bạn

Đăng nhập vào dApp, mở Account ở thanh bên trái, chọn Developers, rồi mở tab Usage.

Tab Usage trên trang Developers, hiển thị cho một key chưa được dùng lần nào.Phóng to hình ảnh

Bộ chọn khoảng thời gian ở trên cùng chuyển giữa Last 24 hours, Last 7 days và Last 30 days. Bên cạnh đó, một chip hiển thị số dư tín dụng của bạn và một chip khác hiển thị hạng tốc độ cùng giới hạn theo giờ đang áp cho các key của bạn. Bên dưới, năm bộ đếm chia khoảng thời gian thành Requests, Successful, Errors, Rate limited và Credits used, còn thẻ Outcome breakdown chia chính khoảng đó thành ba phần.

Quoted vs charged là bảng cần đọc trước khi bạn lo lắng về hóa đơn. Theo đúng lời của sản phẩm, "Quoted is the list price. Charged is what actually came out of your balance." Hai con số không phải lúc nào cũng như nhau, vì các lệnh gọi thất bại, các lệnh gọi bị từ chối và các câu trả lời rỗng một cách trung thực đều được báo giá nhưng không bao giờ bị tính phí.

Request history liệt kê từng lệnh gọi và có thể lọc theo key, endpoint và trạng thái. Hai trạng thái rỗng mang ý nghĩa khác nhau. "No requests match these filters." nghĩa là có các lệnh gọi trong khoảng thời gian này nhưng không cái nào khớp với bộ lọc của bạn, nên hãy nới rộng bộ lọc. "No usage in this window yet." nghĩa là hoàn toàn không có lệnh gọi nào từ bất kỳ key nào của bạn rơi vào khoảng này. Cả hai đều không phải lỗi, và cả hai đều không có nghĩa là một lệnh gọi bị thất lạc. Nếu bạn mong đợi có lưu lượng mà lại thấy con số không, hãy kiểm tra xem ứng dụng của bạn có đang dùng đúng key bạn nghĩ hay không, và nới rộng khoảng thời gian.

Mã lỗi

HTTP	error	Ý nghĩa
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	Dữ liệu vào sai định dạng. chain phải là eth, base hoặc bsc, và địa chỉ phải là 0x cộng 40 ký tự hex.
401	missing_api_key	Không có X-API-Key hoặc Bearer token nào được gửi.
401	invalid_api_key	Key không xác định, hoặc không phải key Cognivo v2.
402	payment_required	Không đủ tín dụng Cognivo cho lệnh gọi này. Không có gì bị tính phí.
403	access_required	Một key cũ chỉ dùng cho siêu dữ liệu đã thử một lệnh gọi live.
403	sandbox_limited	Một key sandbox (cogv_test_) đã thử một lệnh gọi trí tuệ trực tiếp.
403	trial_expired	Hạn mức dùng thử tùy chọn của key đã hết hạn.
403	trial_exhausted	Hạn mức dùng thử tùy chọn của key đã dùng hết.
403	endpoint_denied	Thỏa thuận truy cập của key không bao gồm endpoint này.
403	chain_denied	Key bị giới hạn ở một số mạng nhất định và yêu cầu này nêu một mạng khác. Bị từ chối trước bất kỳ lệnh gọi phía trên nào và trước khi bất kỳ hạn mức nào bị dùng.
403	key_expired	Hạn của key đã qua. Nó bị từ chối ở mọi nơi, kể cả GET /v1/api/me.
403	suspended_key	Key bị đình chỉ và không thể thực thi. Cổng nhà phát triển hiển thị lý do.
403	revoked_api_key	Key đã bị thu hồi hoặc bị thay thế do xoay vòng.
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 hoặc IP và yêu cầu này 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 một kết quả công bằng có căn cứ. Bạn không bị tính phí.
429	rate_limited	Hạn mức tốc độ đã cạn. Phản hồi mang theo Retry-After.
500	internal_error	Lỗi ngoài dự kiến. Hãy kèm request_id khi bạn liên hệ hỗ trợ.
503	pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable	Một trục trặc hiếm gặp về tính phí hoặc thành phần phụ thuộc. Không có gì bị tính phí, nên hãy thử lại.

Mọi phản hồi đều mang request_id, và các phản hồi thành công lặp lại nó ở meta.request_id. Hãy giữ lại. Bộ phận hỗ trợ có thể truy vết một lệnh gọi đơn lẻ từ chính giá trị đó.

Các lỗi thường gặp và cách khắc phục

• 401 missing_api_key. Key chưa bao giờ tới được chỗ chúng tôi. Hãy gửi nó trong header X-API-Key, viết đúng chính xác, hoặc dưới dạng Authorization: Bearer YOUR_API_KEY, và kiểm tra xem có proxy nào đang cắt bỏ header hay không.
• 401 invalid_api_key. Key phải bắt đầu bằng cogv_live_ hoặc cogv_test_. Hãy sao chép toàn bộ key mà không có khoảng trắng thừa xung quanh. 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.
• 402 payment_required. Hãy nạp thêm trên trang thanh toán Cognivo của bạn rồi thử lại. Không có gì bị tính phí. GET /v1/api/me hiển thị số dư hiện tại của bạn.
• 403 revoked_api_key. Hãy 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 vẫn hoạt động nhưng thiếu scope mà endpoint này cần, ví dụ security:read cho wallet/approvals. Xem Xác thực và API key.
• 403 origin_denied. Hãy gọi từ một origin hoặc 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. Đây là một key cũ chỉ dùng cho siêu dữ liệu, có từ trước khi có thanh toán tự phục vụ. Hãy tạo một live key mới trong cổng nhà phát triển.
• 403 sandbox_limited. Key sandbox dùng để kiểm thử và không chạy được trí tuệ trực tiếp. Hãy tạo một live key.
• 403 chain_denied. Hãy kiểm tra allowed_chains trên GET /v1/api/me. Giá trị null ở đó nghĩa là không có hạn chế. Không có gì bị tính phí.
• 403 trial_expired hoặc trial_exhausted. Hạn mức đánh giá tùy chọn đã kết thúc. Bạn không cần bản dùng thử, nên hãy chuyển sang một live key thông thường.
• 403 endpoint_denied. Thỏa thuận của bạn bao gồm các endpoint khác nhưng không bao gồm endpoint này. Hãy đề nghị bổ sung nó.
• 403 suspended_key. Cổng nhà phát triển hiển thị lý do. Hãy liên hệ hỗ trợ từ dApp kèm request_id của bạn nếu chưa rõ.
• 429 rate_limited. Hãy tôn trọng header Retry-After và thêm hàng đợi phía client kèm cơ chế lùi dần, hoặc hỏi về một mức giới hạn cao hơn.
• 400 invalid_chain. Hãy dùng eth, base hoặc bsc. Những tên như ethereum và id chain dạng số không được chấp nhận.
• 400 invalid_address, invalid_wallet, invalid_token. Hãy gửi một địa chỉ đầy đủ gồm 0x cộng 40 ký tự hex. API không phân giải tên ENS hay ký hiệu token.
• 422 insufficient_data. Đây không phải sự cố dịch vụ và cũng không phải lỗi của bạn. Công cụ đã chạy nhưng không thể đưa ra một câu trả lời công bằng có căn cứ, ví dụ wallet/pnl trên một ví không có giao dịch nào được định giá trong token đó. Nó nghĩa là Cognivo không xác minh được câu trả lời, chứ không phải câu trả lời bằng không. Bạn không bao giờ bị tính phí cho một lỗi 422.
• 404 public_api_disabled. API công khai tạm thời bị tắt. Đây không phải URL sai, nên hãy thử lại sau.

Tín dụng và tính phí

Live key là tự phục vụ. Không có đơn đăng ký và không có gói thuê bao. Một live key mới hoạt động ngay lập tức, và mỗi lệnh gọi thành công trừ giá tín dụng của endpoint đó khỏi số dư tín dụng Cognivo của chủ sở hữu dự án, chính là loại tín dụng mà Trò chuyện và dApp sử dụng. Mỗi tài khoản nhận 5 tín dụng miễn phí mỗi ngày, và chúng đặt lại vào nửa đêm UTC. Việc tính phí cho các lệnh gọi Developer API hiện đang tắt, nên một lệnh gọi thành công không trừ gì và số dư của bạn không thay đổi.

Giá tính bằng tín dụng của từng endpoint được in ngay bên cạnh nó trên tab Endpoints của trang Developers, và các endpoint miễn phí được ghi nhãn Free ở đó. Hãy đọc giá từ cổng nhà phát triển thay vì viết cứng nó.

• Lệnh gọi thất bại không bao giờ bị tính phí. Lỗi, hết thời gian chờ, lệnh gọi bị từ chối và các trường hợp vượt giới hạn tốc độ đều không tốn gì.
• Một lệnh gọi thành công chỉ bị tính đúng một lần, nên việc thử lại là an toàn.
• Kết quả rỗng một cách trung thực thì miễn phí. Một lỗi 422, và một danh sách wallet/approvals rỗng, đều là câu trả lời hợp lệ và không bị tính phí.
• Hết tín dụng cho bạn 402 payment_required và không có gì bị tính phí. Hãy nạp thêm trong dApp rồi thử lại.
• Key sandbox (cogv_test_) không bao giờ bị tính phí và không chạy được trí tuệ trực tiếp.
• Key bị đình chỉ và dự án bị vô hiệu hóa không thể thực thi bất cứ thứ gì và không bao giờ bị tính phí.
• Enterprise là con đường yêu cầu dành cho giá tùy chỉnh, giới hạn tùy chỉnh và khối lượng lớn, và bạn yêu cầu nó từ dApp.

Đọc kết quả một cách trung thực

Kết quả của API mô tả những gì Cognivo đã kiểm tra và những gì nó tìm thấy trên chain. Một kết quả sạch không phải là bằng chứng rằng một token hay một ví là an toàn, và một kết quả bị gắn cờ không phải là bằng chứng của gian lận. Một trường thiếu hoặc không khả dụng nghĩa là Cognivo không xác minh được mục đó, chứ không phải là ở đó không có gì. Hãy coi mọi phản hồi là một đầu vào cho nghiên cứu của chính bạn.

Bước tiếp theo

Tra cứu tham số, scope và ví dụ phản hồi trong Tham chiếu endpoint, siết chặt các key của bạn với Xác thực và API key, hoặc xem cách tín dụng hoạt động ở phần còn lại của sản phẩm trong Thanh toán và tín dụng.