Unif API Docsエラー
UnifAPI がエージェントと HTTP クライアントに返すすべてのエラー、その意味、そして回復方法。
エラーは、どの公開データ操作が呼び出されたかに関わらず、常に同じエンベロープで返ります：
{
"error": {
"type": "rate_limited",
"message": "Workspace rate limit exceeded.",
"request_id": "unif_5471f8cfa3814204a280b73df8c93167"
}
}error.typeは 閉じた語彙 からのものです（下の表を参照） — 安定しており、機械可読で、エージェントとクライアントが分岐処理に使うのに安全です。error.messageは人間向けであり、予告なく変更される場合があります。error.request_idは UnifAPI のトレース ID です。サポートリクエストに含めてください。error.issuesはtype = validation_errorの場合にのみ存在します — それは生の Zod issue リストです。
HTTP ステータスは type を反映します — クライアントは好きな方のシグナルを選べます。
リファレンス
| ステータス | type | 発生する状況 | 回復方法 |
|---|---|---|---|
| 400 | validation_error | リクエストがゲートウェイ側の検証に失敗した（不正なクエリ、欠落したボディフィールド）。 | error.issues を確認します。リクエストを修正します。 |
| 400 | invalid_id | 提供された id は構文上有効だったが、公開ソースに受け入れられなかった。 | 実在する id を使用します。 |
| 401 | unauthorized | OAuth または API キーの資格情報が欠落、形式不正、失効、または無効化されている。 | 再認証するか、キーをローテーションします。 |
| 404 | not_found | リソース（動画、ユーザー、ルームなど）が存在しない、削除済み、またはプライベートである。 | id を確認します。一部のリソースはプライベートで、設計上 404 になります。 |
| 429 | rate_limited | ワークスペースまたはソースのレート制限を超過した。 | Retry-After に従います。レート制限 を参照してください。 |
| 500 | internal_error | UnifAPI 自体が失敗した（捕捉されない例外）。 | 再試行して安全です。継続する場合は request_id を報告してください。 |
| 500 | response_shape_error | ソースデータが公開されたスキーマと一致しなくなった。 | request_id を報告してください — ドリフトはバグです。 |
| 502 | upstream_error | 公開データソースが、UnifAPI が回復できないエラーを返した。 | error.message を確認します。 |
| 503 | upstream_unavailable | 公開データソースがタイムアウトしたか、到達不能である。 | 指数バックオフで再試行します。 |
上の表は、現在のエラー語彙に対する公開された契約です。
検証エラーの構造
validation_error の場合、issues 配列は生の Zod issue リストを保持するため、エージェントや呼び出し元はエラーをフィールドに対応付けられます：
{
"error": {
"type": "validation_error",
"message": "Request validation failed.",
"issues": [
{
"code": "too_big",
"maximum": 50,
"type": "number",
"inclusive": true,
"path": ["limit"],
"message": "Number must be less than or equal to 50"
}
]
}
}常に request_id をログに記録する
すべてのエラーレスポンスは、UnifAPI が付与できる場合に request_id を保持します。それをログに記録し、サポートリクエストに含めてください。失敗した Skill の実行や HTTP 呼び出しをデバッグする最速の方法です。