トラブルシューティング
リクエストの文脈とエラーから始め、実行をたどって結果まで確認します。
クライアントが接続できない
URLをこのドキュメントと照らし合わせます。APIはhttps://api.relvo.si、MCPサーバーはhttps://app.relvo.si/mcpです。認証情報が有効で、クライアントが対応する認証方法を使っていることを確認してください。
認証が取り消された、または期限切れになった場合は、クライアントの認証フローで再接続します。npx --yes @relvo/cli doctorは、有料の呼び出しをせずにCLIのログインとMCPの登録を確認します。
ツールが見つからない、アクセスが拒否される
選択中のプロジェクト、アカウントのメンバーシップ、キーのツールアクセスを確認します。認証情報や権限を変えた後は、クライアントのツール一覧を再読み込みしてください。
提供状況は、プロバイダーとアプリで選んだ選択肢によって変わることもあります。
リクエストが拒否される
送信した値を現在の入力スキーマと比べます。必須項目、形式、プロバイダーの選択肢、正確なツールIDを確認してください。
レート制限や割り当ての上限の場合は、再試行する前にエラーと該当プロバイダーの制限を確認します。
結果が返ってこない
実行IDを使って、リクエストがまだ動作中か、失敗したかを確認します。クライアントがタイムアウトしても、背後の実行は続いていることがあります。
サポートに連絡するときは、ツールID、実行ID、時刻、エラーメッセージを控えてください。共有するものからは、認証情報と非公開の入力値を取り除きます。
エラーを読む
エラーはerrorオブジェクトを返します。statusはエラーの種類、messageはほとんどのエラーで変わらないコードです。文言ではなくコードで分岐してください。detailsを付けるエラーもあります。
{
"error": {
"status": "PERMISSION_DENIED",
"message": "platform_api_key_scope_required",
"details": { "scope": "tools:execute" }
}
}ツールと接続の利用拒否は、messageに読める文を、details.codeにコードを入れます。500はInternal service errorを返し、503はplatform_…のコードかService unavailableを返します。どちらも間隔をあけて再試行してください。
主なエラーコード
401 platform_bearer_credential_required
Authorization: Bearer rlv_…を送ってください。
401 platform_developer_api_key_required
RelvoのAPIキー（rlv_…）を送ってください。この認証情報はRelvoのキーではありません。
401 platform_invalid_developer_api_key
新しいキーを作ってください。このキーは存在しないか、取り消し済み・期限切れです。
400 platform_invalid_tool_request
リクエスト本文を直してください。POST /tools/{tool}では、本文のtoolがパスと一致している必要があります。
400 platform_invalid_tool_arguments
details.fieldsのパスを、ツールの入力スキーマに合わせて直してください。
400 platform_idempotency_key_required
使える文字で8〜128文字のIdempotency-Keyを送ってください。
400 platform_quote_changed
見積もり直し、新しいpriceVersionを新しいキーで送ってください。
400 platform_connection_choice_required
details.connectionsから1つ選び、そのIDをconnectionIdに渡してください。
400 platform_provider_own_key_required
アプリでこのプロバイダーの自分のキーを追加するか、別のプロバイダーを選んでください。
403 platform_api_key_scope_required
details.scopeのスコープを持つキーを使ってください。
403 platform_tool_access_denied
details.toolのツールの利用を管理者に依頼してください。
403 platform_approval_required
管理者がdetails.reviewUrlで承認してから再試行してください。
404 platform_tool_unavailable
そのツールはプロジェクトのカタログにありません。
409 platform_idempotency_key_used_for_another_request
別のリクエストには新しいキーを使ってください。
400 platform_body_too_large
本文がエンドポイントの上限を超えています（16 MiBを超えると413）。
429 platform_insufficient_balance_or_spending_limit_reached
残高を追加するか、details.reasonの上限を引き上げてください。
429 platform_request_rate_exceeded
頻度を下げ、間隔をあけて再試行してください。
429 platform_api_key_suspended / platform_organization_suspended
レート制限による拒否が続いたため停止中です。停止が解けるまで待ってください。レート制限と再試行
- 1チームにつき、全キーの合計で毎分2,000リクエスト。キーごとにも同じ上限があります。
GET /toolsでカタログ全体を読むと200リクエスト分に数え、大きなレスポンスは256 KiBごとに1リクエストと数えます。 - レート制限で10分以内に30回拒否されると、キーかチームが15分、次は1時間、その次は24時間停止されます。停止中のリクエストは
429のplatform_api_key_suspendedかplatform_organization_suspendedで失敗します。7日以内に3回停止されたキーは取り消されます。 - 同じIPアドレスから5分以内に30回認証に失敗すると、そのアドレスを一時的に止めます。24時間に3回止まると、24時間使えなくなります。
- 429には
Retry-Afterヘッダーがありません。platform_request_rate_exceededと5xxは、1秒前後から、ゆらぎを入れた指数バックオフで再試行してください。残高・支出上限・アップロード量・ダウンロード回数など、ほかの429は原因を直してから送ります。 - 受け取れなかった送信は、同じ
Idempotency-Keyと同じ本文で再試行します。400・401・403・404は、そのまま送り直さないでください。
サイズの上限
64 KiB
リクエスト本文
1 MiB
見積もり・実行・検索・カスタムツールのリクエスト
16 MiB
アップロードとチームスキルのリクエスト
12 MiB
アップロードするファイル
1 GiB
チームが24時間にアップロードできる量
1 MiB
プロバイダーへの1回のリクエストの出力
14 MiB
上限を上げたカスタムAPIエンドポイントの応答（既定は1 MiB）
64 MiB
生成された成果物
120 s
リクエストを送り終えるまでの時間
300 s
上限を上げたカスタムAPIエンドポイントの1回の呼び出し（既定は5秒）