レート制限、エラー、課金
このページは、インテグレーションが動かなくなる 3 つの原因、つまりリクエスト枠を使い切る、エラーが返る、クレジットを使い切る、についてのリファレンスです。また、その 3 つをアカウントのどこから監視できるかも示します。
昨日まで動いていた呼び出しが見覚えのないコードを返したとき、アプリが何回リクエストできるかを見積もるとき、あるいはリリース前に呼び出しのコストを正確に知りたいときに、このページを開いてください。
レート制限
上限はキーごとに、アクセスモードによって決まります：
| アクセスモード | 上限 |
|---|---|
| ライブ有料：basic（新しいライブキーの既定） | 1 時間あたり 1,000 リクエスト |
| ライブ有料：premium（管理者が付与） | 1 時間あたり 5,000 リクエスト |
| ライブ有料：pro（管理者が付与） | 1 時間あたり 15,000 リクエスト |
| パートナーまたはエンタープライズ | 管理者が設定 |
cogv_test_ のサンドボックスキー全般 | 1 時間あたり 25 リクエスト、1 日あたり 100、1 秒あたり 1 |
有効なキーでのメタデータ面（health、me、discover） | 1 時間あたり 60 リクエスト、1 秒あたり 1 |
新しいライブキーは、承認の手順なしに basic から始まります。premium と pro は Cognivo が付与し、パートナーとエンタープライズの上限は個別の取り決めで設定されます。標準の RateLimit-* ヘッダーがすべての呼び出しで返るため、残りの枠を推測せずに把握できます。枠を使い切ると 429 rate_limited が返り、Retry-After ヘッダーが再試行のタイミングを知らせます。
利用状況の確認
dApp にサインインし、左サイドバーの アカウント を開いて Developers を選び、Usage タブを開きます。
上部の期間セレクターで 過去 24 時間、過去 7 日間、過去 30 日間 を切り替えます。その隣のチップにクレジット残高が、もう 1 つのチップにキーへ適用されるレートティアと 1 時間あたりの上限が表示されます。その下では、5 つのカウンターがその期間をリクエスト、成功、エラー、レート制限、使用クレジットに分解し、結果の内訳 のカードが同じ期間を 3 通りに分けて示します。
提示額と課金額 は、請求を心配する前に読むべきパネルです。製品自身の言葉では「提示額は定価です。課金額は実際に残高から引かれた額です」。この 2 つの数字は必ずしも一致しません。失敗した呼び出し、拒否された呼び出し、正直に空だった答えは、提示はされても課金されないからです。
リクエスト履歴 は個々の呼び出しを一覧表示し、キー、エンドポイント、ステータスで絞り込めます。2 つの空の状態は、それぞれ違うことを意味します。「このフィルターに一致するリクエストはありません。」は、この期間に呼び出しは存在するがフィルター条件に一致するものがない、という意味なので、条件を広げてください。「この期間にはまだ利用がありません。」は、あなたのどのキーからの呼び出しもこの期間にまったく届いていない、という意味です。どちらもエラーではなく、呼び出しが失われたという意味でもありません。トラフィックがあるはずなのにゼロと表示される場合は、アプリが本当に想定どおりのキーを使っているかを確認し、期間を広げてください。
エラーコード
| 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 として繰り返されます。控えておいてください。サポートはその 1 つの値から個別の呼び出しを追跡できます。
よくあるエラーと対処法
- 401
missing_api_key。 キーが Cognivo に届いていません。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です。これは Cognivo が答えを検証できなかったという意味であり、答えがゼロという意味ではありません。422 に課金されることは決してありません。 - 404
public_api_disabled。 公開 API が一時的に停止されています。URL の間違いではないので、しばらくしてから再試行してください。
クレジットと課金
ライブキーはセルフサービスです。申請もサブスクリプションもありません。新しいライブキーはすぐに動き、成功した呼び出しごとに、そのエンドポイントのクレジット価格が プロジェクトのオーナー の Cognivo クレジット残高から差し引かれます。これは Chat や dApp が使うのと同じクレジットです。すべてのアカウントは 1 日あたり 5 クレジットの無料枠を受け取り、UTC の午前 0 時にリセットされます。現在、Developer API の呼び出しに対する課金はオフになっており、成功した呼び出しでも何も差し引かれず、残高は変わりません。
各エンドポイントのクレジット価格は、Developers ページの エンドポイント タブでそれぞれの横に表示され、無料のエンドポイントにはそこで Free と表示されます。価格はハードコードせず、ポータルから読み取ってください。
- 失敗した呼び出しには決して課金されません。 エラー、タイムアウト、拒否された呼び出し、レート制限には費用がかかりません。
- 成功した呼び出しはちょうど一度だけ課金される ため、リトライは安全です。
- 正直に空の結果は無料です。 422 や、空の
wallet/approvalsのリストは有効な答えであり、課金されません。 - クレジット不足 の場合は
402 payment_requiredが返り、何も課金されません。dApp でチャージしてから再試行してください。 - サンドボックス（
cogv_test_）キー は決して課金されず、ライブのインテリジェンスは実行できません。 - 停止されたキーと無効化されたプロジェクト は何も実行できず、課金されることもありません。
- エンタープライズ は、カスタム料金、カスタム上限、大量利用のための申請経路で、dApp から申請します。
結果を正直に読む
API の結果は、Cognivo が何をチェックし、チェーン上で何を見つけたかを説明するものです。クリーンな結果はトークンやウォレットが安全であることの証明ではなく、フラグが立った結果は不正の証明ではありません。フィールドが欠けている、または利用不可である場合は、Cognivo がその項目を検証できなかったという意味であり、そこに何もないという意味ではありません。どのレスポンスも、あなた自身のリサーチにおける 1 つの入力として扱ってください。
次のステップ
パラメーター、スコープ、レスポンスの例は エンドポイントリファレンス で調べ、認証と API キー でキーを絞り込み、製品全体でのクレジットの仕組みは 課金とクレジット をご覧ください。