API エラーコード
System One API のエラー構造、ステータスコード、TypeScript SDK での扱い方。
エラーを処理するときは、HTTP ステータスと分類ヘッダーを根拠に判断してください。Playground は利用者向けのメッセージを表示しますが、アプリケーションは文書化されたレスポンスヘッダーからエラーを分類します。エラーの意味と対処は冪等キーとリトライと同じ原則で扱います。
よくある質問
Q: System One API のエラー処理はどのように行いますか？ A: 一貫したエラー形式と HTTP ステータスコードで表され、TypeScript SDK には型付きのエラーがあります。必要に応じて冪等キーを使ってリトライします。
保存しておく情報
HTTP ステータス、X-System-One-Error-Code、X-Request-Id、リクエスト時刻を保存してください。メッセージの文言を照合するのではなく、ヘッダーのエラーコードで対処を決めてください。API キー、Authorization ヘッダー、機密なリクエスト内容はログに出さないでください)。
エラー元の判別
X-System-One-Error-Code と 함께 X-System-One-Error-Source を読んでください。upstream は、有効なモデルサービスの JSON エラーが元の HTTP ステータス（400〜599）と本文をそのまま保持ことを意味します。その本文はオブジェクト、配列、文字列、他の JSON スカラー、null のいずれでもよく、System One の形式である必要はありません。
安定したヘッダー分類は、上流の HTTP 429／529 を provider_busy、400／422 を provider_rejected_request、その他の上流の失敗を provider_unavailable として扱います。上流の 401／403 は 401／403 のままで、呼び出し側の System One のログインが期限切れだったことを意味しません。platform ソースと provider_* のコードが同時に現れることもあります。これはアカウントの認証問題ではなく、安全に差し替えられたモデルサービスのエラーを示します。
Retry-After は秒数または HTTP 日付で、取得できる場合は保持されます。任意の message や detail の文言をそのまま表示せず、安定した分類からローカライズしたメッセージを作ってください。エラー本文は入力をそのまま返すことがあります。X-Upstream-Request-Id と X-TypeSafe-Request-Id は System One の X-Request-Id とは別の追跡 ID です。
System One のエラー形式
X-System-One-Error-Source: platform は System One のエラーと安全置換を示します。JSON には error.code が含まれます。両方のソースを扱うときはヘッダーの分類を優先してください。
典型的な System One のエラーは次の形です。値は例です。
{
"error": {
"code": "insufficient_credits",
"message": "This request requires 3 credits. Top up your account to continue.",
"request_id": "example-request-id"
},
"request_id": "example-request-id"
}他のエラー本文は異なる形になることがあります。サポートや会計のために、リクエスト ID は X-Request-Id から読み、本文の任意のページから取らないでください。
キーとリクエストの問題
| HTTP | コード | 対処 |
|---|---|---|
| 400 | invalid_json | 重複するオブジェクトキーのない、有効な UTF-8 JSON を送ります。 |
| 401 | invalid_api_key | Bearer キーを確認します。失効または紛失した場合はコンソールで再作成します。 |
| 401 | unauthorized | このエンドポイントには認証済みのアカウントまたはセッションが必要です。サインインします。Bearer キーはコンソールのセッションに代わしません。 |
| 403 | account_disabled | アカウントについてサポートに連絡します。 |
| 404 | not_found | メインアプリケーションのオリジンと文書化されたパスを確認します。 |
| 405 | method_not_allowed | エンドポイントで文書化されたメソッドを使います。意思決定は POST、一覧は GET です。 |
| 413 | request_too_large | リクエスト本文が選択したモデルの上限を超えています。Jev／HTTP モードは 65,536 バイト、画像対応の Clef は最大 13,631,488 バイトです。 |
| 415 | unsupported_media_type | Content-Type: application/json を送ります。 |
| 422 | invalid_request | 示された項目と選択したモデルの上限を確認します。 |
| 422 | unsupported_model | モデル一覧から現在のモデル ID をコピーします。 |
| 422 | invalid_idempotency_key | 操作キーの形式に従います。 |
認証や最初のリクエスト検証の失敗は、新しい意思決定の予約より前に起きるため、意思決定クレジットは課金されません。サポートされないモデルやモデル固有の入力・拡張フィールドの制限も含まれます。選択したカタログ項目の上限を確認してください。サービスの都合で代わりの回答や別のモデルに置き換えることはありません。
残高、上限、繰り返しのリクエスト
| HTTP | コード | 対処 |
|---|---|---|
| 402 | insufficient_credits | 残高を確認します。クレジットを追加するか、質問数かリクエストのサイズを減らします。 |
| 409 | idempotency_conflict | 同じキーを別のリクエストで使いました。復旧には元の本文を復元し、本質的に新しい操作には新しいキーを使います。 |
| 409 | request_in_progress | Retry-After を待ち、同じキーと同じ本文でリトライします。 |
| 409 | idempotency_failed | 元の操作が失敗し、クレジットが返金されました。意図的な再試行にだけ新しいキーを使います。 |
| 409 | request_expired | 操作が完了する前に終了し、クレジットが返金されました。記録を確認してからやり直します。 |
| 410 | idempotency_expired | 元の回答はリプレイ用に保持されていません。元の操作を確認します。 |
| 429 | rate_limit_exceeded | Retry-After を待ちます。API キーと Playground はアカウントの意思決定上限を共有します。 |
リプレイ保護はリクエスト作成から 24 時間です。期限切れのキーは 410 を返さずに新しい課金対象の操作を開始できます。意思決定の試行は、キーと Playground をまたいでアカウントのウィンドウを共有します（既定は毎分 120 回）で、リプレイの試行も含みます。モデル一覧にはアカウントごとに毎分 60 回という別の上限があります。429 のとき、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset がウィンドウを説明し、Retry-After が待ち時間を秒で示します。リセット値は期間ではなく秒単位の Unix タイムスタンプです。上流の上限は X-Upstream-RateLimit-* という別の名前空間です。
サービスの問題
| HTTP | コード | 対処 |
|---|---|---|
| 429 / 529 | provider_busy | モデルサービスが混雑しています。Retry-After を尊重し、記録された結果を確認してから再試行します。 |
| 400 / 422 | provider_rejected_request | リクエストと選択したモデルの要件を確認します。 |
| 502 など | provider_unavailable | モデルリクエストを完了できませんでした。結果を確認し、続く場合はサポートに連絡します。 |
| 502 | invalid_provider_response | モデルが不正、安全でない、JSON でない、不正な UTF-8、1MB 超え、またはリダイレクトのレスポンスを返しました。既定の意思決定は生成されません。 |
| 504 | provider_timeout | ヘッダーと本文を含む 20 秒のモデル応答の期限が切れました。記録された結果を確認します。 |
| 499 | request_cancelled | リクエストがキャンセルされました。記録を確認してから新しい操作を送ります。 |
| 503 | provider_not_configured, provider_configuration_error | サービスの設定が必要です。サポートに連絡します。サービスの設定を変更する必要はありません。 |
| 503 | model_catalog_unavailable | 現在のモデルカタログを読み込めませんでした。新しい評価は始まっていません。後でリトライするかサポートに連絡します。 |
| 501 | model_listing_not_supported | この接続ではモデル一覧を利用できません。Playground のセレクターを使い、必要ならサポートに連絡します。 |
| 503 | request_reconciliation_pending | このリクエストの課金はまだ確定していません。ID を保存し、コンソールの利用状況を確認します。ヘッダーが無いことは 0 を意味しません。 |
| 500 | internal_error | リクエスト ID を保存し、元の操作を確認してからやり直します。 |
リトライ前の課金確認
通常の失敗した評価は、その試行で予約したクレジットを返します。X-System-One-Credits: 0 はその試行に残った課金がないことを示します。即時の照合ができない場合、サービスは request_reconciliation_pending を返し、このヘッダーを省略します。課金ヘッダーが無いことは 0 ではありません。 クレジットと課金とコンソールの利用記録を確認してください。
自前のツールでタイムアウトや接続断が起きても、操作が失敗したとは限りません。同じ操作キーと同じ本文で復旧します。失敗と返金が確認できた後の再試行には新しいキーが必要です。新しくキーを発行しての自動リトライは避けてください。
SDK でのエラー処理
@system-one-ai/core@0.8.0 は statusCode、requestId、retryAfterMs を持つ APIError を公開しますが、サーバーのエラー本文全体や分類ヘッダーは含みません。複数の 409 を区別する必要がある統合では Fetch を使ってください。独立して保守されている公式の @typesafe-ai/sdk@0.6.0 は独自のエラークラスを持ちます。どちらのクライアントも同じ形を公開するとは考えず、エラーオブジェクトをそのままログに出さないでください。
クライアントのリトライポリシーはサービスとは別です。サービスはモデルの推論を自動的にリトライしません。不明な応答の後は、保持したキーと本文で復旧します。失敗と返金が記録された後、同じキーは idempotency_failed を返します。意図的な再試行にだけ新しいキーを使ってください。
解決しないエラーや課金については、リクエスト ID、時刻、ステータス、エラーコードを添えて support@system-one.devへ連絡してください。API キーや機密な送信内容を含めてはいけません。
内部リンク
API リファレンス、冪等キー（Idempotency key）、API バージョニング、クレジットと課金を参照してください。