API エラーリファレンス

このガイドは、TeamDay API のすべてのエラーコード、レスポンス形式、トラブルシューティング手順を文書化しています。

---

エラーレスポンス形式

すべての API エラーは一貫性のある JSON 構造に従います：

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Detailed error description"
}

フィールド:

• error (boolean) - エラーレスポンスでは常に true
• statusCode (number) - HTTP ステータスコード
• statusMessage (string) - 人間が読める状態メッセージ
• message (string) - 詳細なエラー説明

---

HTTP ステータスコード

2xx 成功

これらはエラーではなく、成功レスポンスです：

200 OK

意味: リクエストが成功

使用:

• GET リクエスト (リスト、詳細取得)
• PATCH リクエスト (更新)
• DELETE リクエスト (ソフト削除)
• POST リクエスト (実行キャンセル)

例:

{
  "id": "agent_abc123",
  "name": "Research Assistant",
  "...": "..."
}

201 Created

意味: リソースが正常に作成

使用:

• POST リクエスト (エージェント作成、タスク作成)

例:

{
  "id": "agent_abc123",
  "name": "Research Assistant",
  "createdAt": "2025-12-09T10:00:00Z",
  "...": "..."
}

---

4xx クライアントエラー

これらのエラーはリクエストの問題を示します。

400 Bad Request

意味: 無効なリクエストパラメータまたは必須フィールドが不足

一般的な原因:

• 必須フィールドが不足
• 無効なフィールド値
• 不正な形式の JSON
• 無効なクエリパラメータ

例:

必須フィールドが不足:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Missing required field: name"
}

無効な可視性値:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Invalid visibility value. Must be: private, organization, or public"
}

無効なステータス:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Invalid status. Must be: pending, in_progress, completed, cancelled"
}

不正な形式の JSON:

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Invalid JSON in request body"
}

修正方法:

1. リクエスト本文が API ドキュメントと一致することを確認
2. すべての必須フィールドが存在することを確認
3. フィールド値が有効であることを確認 (列挙型、型)
4. JSON 検証ツールで JSON 構文をテスト

---

401 権限なし

意味: 認証に失敗または不足

一般的な原因:

• Authorization ヘッダーが不足
• 無効なトークン
• 期限切れのトークン
• トークン形式が不正

詳細については、エラーリファレンス を参照してください。