AI Coding Assistant Lingma:エラー

エラーエンベロープ

すべてのエラーレスポンスは、次の JSON 構造に従います。

",
    "message": "",
    "param": ""
  }
}{
  "type": "error",
  "error": {
    "type": "

フィールドの説明

フィールド	タイプ	必須	説明
type	string	はい	常に "error"
error.type	string	はい	エラータイプの識別子
error.message	string	はい	人間が読める形式のエラー説明
error.param	string	いいえ	エラーの原因となったリクエストパラメーター名

エラータイプ

HTTP ステータス	error.type	説明
400	invalid_request_error	リクエストパラメーターが無効または欠落しています
401	authentication_error	認証に失敗しました。トークンが欠落しているか、無効です
403	permission_error	認証されていますが、リソースに対して認可されていません
404	not_found_error	対象リソースが存在しません
409	conflict_error	リソースの状態の競合 (例：重複作成)
500	api_error	内部サーバーエラー

エラータイプの詳細

400 — invalid_request_error

リクエストのフォーマットまたはパラメーターが無効です。

一般的なトリガー：

• 必須フィールド (例：name) の欠落
• フィールドタイプの不一致 (文字列が期待される箇所に数値が指定されている場合など)
• ボディが 4 MB の制限を超えている
• 不正な形式の JSON

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required field: name",
    "param": "name"
  }
}

# 実行例：name フィールドの欠落
curl -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{}'

401 — authentication_error

認証に失敗しました。

一般的なトリガー：

• Authorization ヘッダーの欠落
• 不正な形式の PAT
• PAT の有効期限切れまたは失効
• ベアラートークンの代わりに x-api-key が使用されている

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key or token."
  }
}

# 実行例：無効なトークン
curl -s https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer pt-invalid-token"

403 — permission_error

認証済みですが、認可されていません。

一般的なトリガー：

• PAT が対象のエージェントにアクセスできない (異なるユーザーまたは組織)
• PAT のスコープにこの操作が含まれていない
• アーカイブされロックされたリソースを操作しようとしている

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "You do not have permission to access this agent."
  }
}

# 実行例：他のユーザーのエージェントへのアクセス
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_other_user_123 \
  -H "Authorization: Bearer $QODER_PAT"

404 — not_found_error

対象リソースが存在しません。

一般的なトリガー：

• エージェント、セッション、または環境の ID が存在しない
• リソースが削除されている
• URL パスのタイプミス

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "Agent not found: agent_nonexistent_123"
  }
}

# 実行例：存在しないエージェント
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_nonexistent_123 \
  -H "Authorization: Bearer $QODER_PAT"

409 — conflict_error

リソースの状態が競合しているため、操作を実行できません。

一般的なトリガー：

• 同じべき等キーが、異なるリクエストボディで再利用された場合
• 終了したセッションを操作しようとしている
• 一意の名前を持つリソースを重複して作成しようとしている

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "A request with this idempotency key has already been processed with different parameters."
  }
}

500 — api_error

内部サーバーエラー。

一般的なトリガー：

• サービスが一時的に利用できない
• 内部コンポーネントの障害
• データベース接続のタイムアウト

{
  "type": "error",
  "error": {
    "type": "api_error",
    "message": "An internal error occurred. Please try again later."
  }
}

エラー処理のベストプラクティス

1. HTTP ステータスコードではなく、error.type で分岐してください。
2. 診断のために error.message をログに記録してください。
3. error.param を調べて、問題のあるフィールドを特定してください。
4. リクエストが変更されない限り、4xx エラーはリトライしないでください。
5. 5xx エラーは、エクスポネンシャルバックオフを使用してリトライしてください (最大 3 回まで)。

# エラー処理を含むリクエスト
response=$(curl -s -w "\n%{http_code}" \
  https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT")

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | sed '$d')

if [ "$http_code" -ge 400 ]; then
  error_type=$(echo "$body" | python3 -c "import sys,json; print(json.load(sys.stdin)['error']['type'])")
  echo "API error: $error_type"
fi