レート制限、エラー、課金
レート制限
制限はキーごと、アクセスモード別です：
| アクセスモード | 制限 |
|---|---|
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 | 1 時間分のティア予算を使い切りました |
| 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 の結果はオンチェーンインテリジェンスシグナルであり、投資助言ではありません。レッドフラグがないことは安全の証明ではありません。必ずご自身で調査してください。