エラー
Nodaro の TypeScript SDK がスローするすべてのエラーを、HTTP ステータス、コード、フィールドとともに説明し、クレジット、レート制限、競合、失敗したジョブへの対処法も扱います。
Nodaro SDK が API の応答に対してスローするエラーは、すべて NodaroError かそのサブクラスのインスタンスです。エラーステータスで失敗したリクエストは、そのステータスに対応するサブクラスをスローします。run-and-wait のヘルパーは、ジョブが失敗、タイムアウト、停止したときに、それぞれ専用のサブクラスをスローします。具体的なクラスから先にキャッチし、NodaroError は最後にキャッチしてください。
すべてのエラークラス
| クラス | ステータス | code | 追加のフィールド | スローされる条件 |
|---|---|---|---|---|
NodaroError | いずれか | サーバー自身のコードです | 基底クラスで、より具体的なクラスがないすべてのエラーです | |
UnauthorizedError | 401 | unauthorized | トークンが未指定か、期限切れか、無効です | |
ForbiddenError | 403 | サーバーのコード、なければ forbidden | missingScope? | 権限がない、または OAuth トークンにスコープが不足しています |
ModelUnavailableError | 403 | model_not_available または model_disabled | 選んだモデルが提供されていない、または管理者がオフにしました | |
ImportRefusedError | 403 | imports_blocked、import_source_disabled、link_imports_disabled または rights_* コード | リンクのインポートが、何かを取得する前に拒否されました | |
NotFoundError | 404 | サーバーのコード、なければ not_found | 項目が存在しない、またはあなたには見えません | |
RateLimitedError | 429 | サーバーのコード、なければ rate_limited | リクエストが多すぎます | |
InsufficientCreditsError | 402 | insufficient_credits、またはほかの 402 のコード | required?、available? | アカウントが、実行の料金を払えません |
CreditCapExceededError | 402 | budget_exceeded、member_cap_exceeded、user_allowance_exceeded | required?、available? | ほかの人が設定した支出の上限が、実行を拒否しました |
StorageExceededError | 413 | storage_exceeded | limitBytes?、reason? | 送ったものが収まりません。ストレージがいっぱいか、1 つのファイルが上限を超えています |
WorkflowConflictError | 409 | workflow_conflict または production_busy | currentUpdatedAt?、currentVersion?、currentRecord? | 先に、ほかの人がその項目を変更しました |
AlreadyRunningError | 409 | already_running | executionId | 開始または続行を求めた実行が、まだ進行中です |
AppRunVersionChangedError | 409 | app_run_version_changed | runVersion?、appVersion? | アプリのバージョンが変わったため、アプリの実行の再試行が拒否されました |
JobBlockedError | 422 | job_blocked | デプロイ環境のコンテンツポリシーが、リクエストを拒否しました | |
MediaTooLongError | 422 | media_too_long | 大容量アップロードのファイルが 30 分より長い | |
LargeUploadUnavailableError | 409 または 404 | large_upload_unavailable | 大容量アップロードのルートがないサーバーで、500 MB を超えるファイルを送った | |
StudioOpError | 4xx | サーバー自身のコードです | opIndex | スタジオのバッチ内の 1 つの操作が、拒否されました |
JobFailedError | 0 | job_failed | jobId、jobStatus | 待っていたジョブが、失敗またはキャンセルされました |
JobTimeoutError | 0 | job_timeout | jobId、timeoutMs | ジョブが maxMs 以内に終わりませんでした |
JobAbortedError | 0 | job_aborted | jobId? | 待っている間に、自分の AbortSignal が発火しました |
JobHeldError | 0 | job_held | jobId | ジョブが、人によるレビューのために保留されています |
StudioPreviewUnavailable | 0 | studio_preview_unavailable | デプロイ環境が、スタジオのバッチをプレビューできません | |
StudioPreviewAppliedError | 0 | studio_preview_applied | applied | プレビューを求めたスタジオのバッチが、適用されました |
どのクラスにも、4 つのフィールドがあります。読みやすい文である message、比較できる安定した文字列である code、HTTP ステータスである status、そして details です。status が 0 の場合、そのエラーは HTTP の応答から来たものではないことを意味します。たとえば JobTimeoutError は、SDK 自身のポーリングループがスローします。
details には、エラーエンベロープの code と message 以外のすべてのフィールドが、サーバーが送ったとおりに入ります。たとえば、トレンドの拒否の slot、公開の拒否の reasons、検証エラーの issues です。エンベロープにほかに何もなかった場合と、SDK 自身が作ったエラーでは、{} です。
try {
await client.trends.run(slug, request)
} catch (err) {
if (err instanceof NodaroError && err.code === "missing_slot") askFor(err.details.slot as string)
}コンストラクターは new NodaroError(message, code, status, details?) です。
一部のステータスは、サーバーが送ったコードにかかわらず、1 つのクラスに対応づけられます。403 は ForbiddenError になります。ただし、拒否されたモデルは ModelUnavailableError に、拒否されたリンクのインポートは ImportRefusedError になります。404 は NotFoundError に、429 は RateLimitedError になり、413 はすべて StorageExceededError になります。ForbiddenError、NotFoundError、RateLimitedError は、node_not_available、continuation_not_found、rate_limit_exceeded のような、サーバー自身の code を保持します。サーバーがコードを送らなかった場合にだけ、forbidden、not_found、rate_limited になります。409 が WorkflowConflictError になるのは、コードが workflow_conflict または production_busy の場合だけです。executionId を示す 409 の already_running は AlreadyRunningError になり、409 の app_run_version_changed は AppRunVersionChangedError になります。400 や 503 など、それ以外のステータスのエラーと、ほかのコードの 409 は、サーバー自身の code を持つ NodaroError として届きます。
エラーを順番にキャッチする
import {
ForbiddenError,
InsufficientCreditsError,
ModelUnavailableError,
NodaroError,
NotFoundError,
RateLimitedError,
StorageExceededError,
UnauthorizedError,
} from "@nodaro/sdk"
try {
await client.workflows.run(workflowId)
} catch (err) {
if (err instanceof UnauthorizedError) {
redirectToLogin()
} else if (err instanceof ModelUnavailableError) {
showError("This model is not available. Choose another model.")
} else if (err instanceof ForbiddenError) {
if (err.missingScope) requestAdditionalScopes([err.missingScope])
else showError("You do not have permission to do this.")
} else if (err instanceof InsufficientCreditsError) {
showCreditPaywall({ required: err.required, available: err.available })
} else if (err instanceof RateLimitedError) {
await retryWithBackoff()
} else if (err instanceof StorageExceededError) {
if (err.reason === "file_too_large") showError("This file is too large.")
else showError(`Storage limit of ${err.limitBytes} bytes reached.`)
} else if (err instanceof NotFoundError) {
showError("Not found.")
} else if (err instanceof NodaroError) {
console.error(`API error ${err.status} (${err.code}): ${err.message}`)
} else {
throw err // a network failure or a timeout, not an API answer
}
}クライアントの timeoutMs を超えたリクエストと、ネットワークの障害は、どちらもランタイム自身のエラー(AbortError や TypeError など)を伴って失敗します。これらは NodaroError のインスタンスではありません。
認証と権限
UnauthorizedError
HTTP 401 です。トークンが未指定か、期限切れか、無効です。新しいトークンを取得するか、ユーザーにもう一度ログインしてもらってから、再試行してください。
ForbiddenError
HTTP 403 です。呼び出し元に、この操作を行う権限がありません。OAuth トークンに、エンドポイントが必要とするスコープが許可されていない場合、missingScope にそのスコープの名前が入ります。たとえば workflows:execute です。ユーザーにそのスコープを承認してもらい、新しいトークンで再試行してください。スコープと権限の不足を参照してください。
ほかの理由には、その機能を提供していないエディションであることや、ロールの権限が低すぎることがあります。code は、insufficient_scope や node_not_available のようなサーバー自身のコードなので、そのコードで分岐できます。サーバーがコードを送らなかった場合にだけ、forbidden になります。
ModelUnavailableError
呼び出し元ではなく、モデルを拒否する HTTP 403 です。Nodaro は、クレジットを確保する前にこの応答を返します。別のモデルを選んでください。再試行しても、クレジットを追加しても、スコープを広げても、結果は変わりません。
code | 拒否の理由 |
|---|---|
model_not_available | このデプロイ環境は、そのモデルを提供していません。モデルがエディションや提供面の対象外であるか、運営者がモデルを非表示にしています。 |
model_disabled | 管理者がモデルをオフにしました。 |
ModelUnavailableError は ForbiddenError を継承しているため、既存の instanceof ForbiddenError のチェックでもキャッチされます。2 つを区別するには、先に instanceof ModelUnavailableError を調べてください。英語の message ではなく、code を読んで独自の文を表示してください。ReadonlySet<ModelUnavailableCode> である MODEL_UNAVAILABLE_CODES に、2 つのコードが含まれています。このエラーはモデルの名前を示しません。拒否されたモデルは、リクエストの provider です。複数のモデルを実行するリクエストでは、その models のいずれかです。insufficient_scope の 403、ほかのコードの 403、コードのない 403 は、通常の ForbiddenError のままです。
コンストラクターは new ModelUnavailableError(code, message?) です。ForbiddenError のコンストラクターは new ForbiddenError(message?, missingScope?, code?) です。
ImportRefusedError
リンクのインポートを、何かを取得する前に拒否する HTTP 403 です。対象は media.downloadVideo()、uploads.importUrl()、オーディオのインポートです。アカウントへの措置、コンテンツ権利のチェック、またはデプロイ環境のサイトのポリシーが拒否しました。コンテンツ権利と繰り返し侵害者を参照してください。
code | 拒否の理由 |
|---|---|
imports_blocked | デプロイ環境の繰り返し侵害者ポリシーにより、アカウントでリンクのインポートがブロックされているか、アカウントが閉鎖されています。メッセージには、いつまでかが示されます。UTC の日付、または管理者がブロックを解除するまでです。 |
import_source_disabled | デプロイ環境が、リンク先のサイトからのインポートを許可していません。メッセージはサイトの名前を示しません。 |
link_imports_disabled | デプロイ環境が、ほかのサイトへのリンクからのインポートをオフにしています。ほかのサイトへのリンクは拒否されるので、代わりにファイルをアップロードしてください。デプロイ環境自身のストレージのファイルは拒否されません。 |
rights_confirmation_required | デプロイ環境が確認を必須としていますが、確認が送られていません。 |
rights_authorization_required | デプロイ環境が確認を必須としており、インポートが API キー、接続済みアプリ、または AI エージェントを通じて行われましたが、アカウントに継続的な承認がありません。本人が自分のセッションで、contentRights.authorize() を使って承認します。 |
rights_confirmation_not_found | その ID の確認はありません。 |
rights_confirmation_mismatch | 確認が、別のリンクまたは別のアカウントのものです。 |
rights_confirmation_stale | 宣言が変わりました。もう一度読み、もう一度確認してください。 |
rights_confirmation_expired | 確認から 1 時間を超えています。 |
rights_confirmation_used | その確認で、すでにインポートが行われました。取得が始まった後に失敗したインポートも数えられます。 |
rights_confirmation_* コードの場合は、client.contentRights.confirm({ url, declarationVersion }) をもう一度呼び出し、新しい ID でもう一度インポートしてください。ImportRefusedError は ForbiddenError を継承しているため、既存の instanceof ForbiddenError のチェックでもキャッチされます。先に instanceof ImportRefusedError を調べ、code を読んで独自の文を表示してください。ReadonlySet<ImportRefusalCode> である IMPORT_REFUSAL_CODES に、これらのコードが含まれています。コンストラクターは new ImportRefusedError(code, message?) です。
NotFoundError
HTTP 404 です。項目が存在しない、またはこの呼び出し元には見えないことを意味します。Nodaro はどちらの場合も同じように応答するため、ID によって、見えないものが存在するかどうかがわかることはありません。スタジオプロダクションや Recast のように、Nodaro Cloud にしか存在しないリソースも、セルフホスティング環境では 404 を返します。
code は、continuation_not_found のようなサーバー自身のコードです。存在しないルートのように、サーバーがコードを送らなかった場合は not_found になります。コンストラクターは new NotFoundError(message?, code?) です。
クレジット、ストレージ、上限
InsufficientCreditsError
HTTP 402 です。アカウントが実行の料金を払えないため、何も開始されませんでした。required は実行に必要なクレジットの数、available はアカウントが持つクレジットの数、上限の場合はその上限の残りです。どちらも Nodaro Cloud が設定しますが、型としては省略可能です。code はその拒否自体のコードです。自分の残高の場合とサーバーがコードを送らなかった場合は insufficient_credits、それ以外は free_video_limit や insufficient_app_credits などの別の 402 のコードです。
try {
await client.nodes.runAndWait("generate-video", params)
} catch (err) {
if (err instanceof InsufficientCreditsError) {
console.log(`Need ${err.required} credits, have ${err.available}`)
}
}実行の前に、client.credits.balance() で残高を確認してください。クレジットを参照してください。
CreditCapExceededError
自分の残高ではなく、ほかの人が設定した支出の上限による HTTP 402 です。チャージしても解決しません。上限を設定した人が引き上げる必要があります。
code | 上限 |
|---|---|
budget_exceeded | ワークスペースの予算 |
member_cap_exceeded | そのワークスペースでの自分のクレジットの上限 |
user_allowance_exceeded | デプロイ環境のユーザーごとの割り当て |
CreditCapExceededError は InsufficientCreditsError を継承しているので、既存の instanceof InsufficientCreditsError のチェックでも捕捉されます。2 つを区別するには、先に instanceof CreditCapExceededError を確認してください。CREDIT_CAP_CODES(ReadonlySet<CreditCapCode>)に 3 つのコードが入っています。
StorageExceededError
HTTP 413 です。送ったものが収まらないことを示します。ルートにかかわらず、413 はすべてこのクラスとして届き、reason がその種類を示します。
reason | 意味 |
|---|---|
storage_limit_exceeded | アカウントのストレージがいっぱいです。limitBytes がその上限です。不要なメディアを削除してから、再試行してください。 |
file_too_large | 1 つのファイルがサイズの上限を超えています。ストレージはいっぱいではありません。小さいファイルを送ってください。 |
payload_too_large、post_too_large、duration_exceeded | リクエスト、投稿、またはメディアの長さが上限を超えています。ストレージはいっぱいではありません。 |
応答にコードがなかった場合、reason は undefined です。アップロードや、コミュニティの複製のようにストレージへのコピーを行う処理で、このエラーがスローされます。コンストラクターは new StorageExceededError(message?, limitBytes?, reason?) です。
RateLimitedError
HTTP 429 です。リクエストを送りすぎました。待ってから、間隔を広げながら再試行してください。たとえば 2 秒、次に 4 秒、次に 8 秒です。何度か試したら止めてください。レート制限を参照してください。
code は、rate_limit_exceeded のようなサーバー自身のコードです。サーバーがコードを送らなかった場合は rate_limited になります。コンストラクターは new RateLimitedError(message?, code?) です。
ジョブを待つ
client.nodes.runAndWait()、client.nodes.runMany()、そしてほかのリソースの ...AndWait ヘルパーは、ジョブが終わるまでポーリングします。待っている間、これらは次のエラーをスローします。
JobFailedError
ジョブが failed または cancelled のステータスで終わりました。どちらであるかは jobStatus が示し、jobId はそのジョブを、message はジョブ自身のエラーメッセージを示します。client.jobs.get(err.jobId) でジョブ全体を読み取ってください。その error_hint が、安全フィルターやポリシーによるブロックを説明します。
JobTimeoutError
ジョブが maxMs(デフォルトは 15 分)以内に、終了状態に達しませんでした。ジョブはキャンセルされません。たいていはそのままサーバー上で完了し、あなたのライブラリに届きます。後から client.jobs.get(err.jobId) で取得するか、遅いモデルには、より大きな maxMs を渡してください。プラットフォームが復旧中のジョブは、そのステータスに recovering: true が示され、復旧には数十分かかることがあります。
JobAbortedError
自分の AbortSignal が発火しました。SDK はただちにポーリングを止めます。ジョブはキャンセルされません。サーバー上でジョブを止め、確保されていたクレジットを返還するには、client.jobs.cancel(err.jobId) を呼び出してください。
JobHeldError
ジョブが pending_review のステータスに達しました。このデプロイ環境のコンテンツポリシーが、人によるレビューのために結果を保留したことを意味します。SDK は、このステータスを最初に確認したポーリングで、待機を止めます。ジョブはキャンセルされず、レビューの間、クレジットは確保されたままです。リクエストをもう一度実行しないでください。重複したジョブも、同じように保留されるためです。
後から client.jobs.get(err.jobId) でジョブを確認してください。レビュー担当者が承認すると completed に、却下すると failed になり、あなたがキャンセルすると cancelled になります。却下されたジョブには、policy-block に設定された error_hint.kind と、そのまま表示できる reason が含まれます。このエラーが起きるのは、ジョブのポリシーを登録しているデプロイ環境だけです。
JobBlockedError
HTTP 422 で、コードは job_blocked です。このデプロイ環境のジョブポリシーまたはコンテンツガードが、実行される前にリクエストを拒否しました。ジョブは作成されず、料金も発生していません。message はユーザー向けに書かれているため、そのまま表示してください。同じリクエストを再試行しないでください。このエラーが起きるのは、ジョブのポリシーを登録しているデプロイ環境だけです。
大容量アップロード
MediaTooLongError
HTTP 422、コード media_too_long です。uploads.uploadLarge が、アップロードの完了時にスローします。ファイルが、エディターに取り込めるメディアの上限である 30 分より長い場合です。保存されたコピーは削除され、ストレージの使用量には何も数えられません。ファイルを短くして、もう一度アップロードしてください。コンストラクターは new MediaTooLongError(message?) です。
LargeUploadUnavailableError
コードは large_upload_unavailable です。uploads.uploadLarge に 500 MB(UPLOAD_MAX_BYTES)を超えるファイルが渡され、サーバーに大容量アップロードのルートがありません。status は、デプロイメントがルートを閉じている場合は 409 です。すべてのアップロードのバイトをアップロードポリシーで確認しているためです。ルートを持たない古いサーバーでは 404 です。POST /v1/upload の上限は 500 MB なので、そのサーバーはこのファイルを受け付けられません。ファイルを小さくするか、分割してください。コンストラクターは new LargeUploadUnavailableError(message?, status?) です。
同時に行われた変更
WorkflowConflictError
HTTP 409 です。条件付きの変更を行おうとしたところ、先にほかの人がその項目を変更していました。次の 2 つのコードのいずれかで届きます。
workflow_conflict:expectedVersionまたはexpectedUpdatedAtを指定したclient.workflows.update()が、保存されているワークフローと一致しませんでした。production_busy:サーバーがあなたの変更を適用している間も、スタジオプロダクションが変化し続けたため、サーバーが再試行を止めました。
どちらも対処法は同じです。項目をもう一度読み取り、最新のコピーに変更を適用して、もう一度送信してください。サーバーが含めている場合、currentRecord に現在のワークフローが入っているため、もう一度読み取らずにマージできます。
import { WorkflowConflictError } from "@nodaro/sdk"
try {
await client.workflows.update(id, { settings, expectedVersion: loadedVersion })
} catch (err) {
if (err instanceof WorkflowConflictError && err.currentRecord) {
const merged = mergeSettings(err.currentRecord.settings, settings)
await client.workflows.update(id, { settings: merged, expectedVersion: err.currentVersion })
} else {
throw err
}
}AlreadyRunningError
コードが already_running の HTTP 409 です。開始または続行を求めた実行がまだ進行中で、executionId がその実行を示します。もう一度開始する代わりに、client.executions.get(executionId) でその実行を追ってください。client.workflows.run() は、そのワークフローの実行が進行中の間にこのエラーをスローします。client.apps.resume() は、その実行の再試行が保留中の間にこのエラーをスローします。
このクラスが選ばれるのは、409 に executionId が含まれている場合です。何も示さない 409 は、通常の NodaroError のままです。
AppRunVersionChangedError
コードが app_run_version_changed の HTTP 409 です。client.apps.resume() による失敗したアプリの実行の再試行が、アプリのバージョンが実行のバージョンと異なるために拒否されました。何も書き込まれず、課金もされていません。
runVersion:実行が実行したバージョンです。appVersion:現在のバージョンです。送信したversion、なければアプリの最新バージョンです。
応答にこれらが含まれない場合、どちらのフィールドも undefined です。アプリの現在のバージョンを実行するには、client.apps.run() で実行を最初からやり直します。実行自体のバージョンのまま続けるには、{ version: err.runVersion } を付けて、もう一度 resume を呼び出します。
ロケーションとオブジェクトは、独自の競合コードである concurrent_modification を使い、これは通常の NodaroError として届きます。対処法は同じです。項目をもう一度読み取り、マージしてから再試行してください。
スタジオのバッチ
この 3 つのクラスは、スタジオプロダクションに関するものです。
StudioOpError:操作のバッチが拒否され、opIndexにはその原因となった操作の位置が、0 から数えて入ります。バッチ内のものは何も書き込まれていません。その操作を修正して、バッチ全体をもう一度送信してください。StudioPreviewUnavailable:dryRun: trueを付けてプレビューを求めたものの、このデプロイ環境ではプレビューを提供できません。バッチは送信されていません。プレビューが利用できないことをユーザーに伝え、確認なしにバッチを適用しないでください。StudioPreviewAppliedError:プレビューを求めたにもかかわらず、バッチが適用されてしまいました。applied.productionとapplied.versionを、現在の状態として扱ってください。バッチをもう一度送信しないでください。appliedがundefinedの場合は、何かを決める前に、プロダクションをもう一度読み取ってください。
NodaroError で見られるコード
これらのコードは、通常の NodaroError に付いて届きます。err.code を比較して処理してください。
| ステータス | コード | 対象 | 意味 |
|---|---|---|---|
| 400 | validation_error | 多くのメソッド | フィールドが不足しているか、無効です。message にその名前が示されます。 |
| 400 | no_valid_inputs | client.reduce.run() | すべての入力が空でした。 |
| 400 | invalid_edl | client.edit.applyEdl() | 編集決定リストが、検証に失敗しました。 |
| 400 | limit_reached | client.developerApps.create() | すでにアプリの上限数に達しています。 |
| 400 | locked_field | client.apps.run() | オーバーライドが、Webhook の URL など、送信先を変更しようとしました。 |
| 409 | name_taken | キャラクター、組織 | 名前またはスラッグが、すでに使われています。 |
| 409 | concurrent_modification | ロケーション、オブジェクト | 読み取った後に、項目が変更されました。 |
| 410 | voice_cloning_retired | client.voices.createClone() | ボイスクローニングは、もう提供されていません。代わりにボイスデザインを使ってください。 |
| 400 | quote_unsupported | client.nodes.quote() | プラットフォームは、このノードタイプを見積もれません。メッセージに、見積もれるタイプが一覧表示されます。 |
| 400、502 | advanced_mode_unavailable | client.llm.structured() | モデル自体のプロバイダーが、現在、詳細モードのリクエストを受け付けられません。モデルを実行するには、詳細モードをオフにしてください。 |
| 409 | job_cancelled | client.llm.structured() などの従量課金の LLM リクエスト | クレジットの確保後、呼び出しが送られる前にジョブがキャンセルされました。何も課金されません。ジョブは意図的にキャンセルされたものなので、そのまま再試行しないでください。 |
| 503 | job_start_failed | 従量課金の LLM リクエスト | サーバーが呼び出しの開始を記録できなかったため、呼び出しを送りませんでした。何も課金されません。再試行してください。 |
| 503 | provider_unavailable | client.llm.structuredJob() | このインスタンスでは、このモデルを実行できません。再試行しないでください。 |
| 503 | feature_disabled | client.copilot | この機能は、このデプロイ環境ではオフになっています。 |
| 503 | nodaro_connection_required | client.edit.editPlan() | セルフホスティング環境でこれを使うには、Nodaro Cloud への接続が必要です。 |
各リファレンスページには、そのページ自身のメソッドのコードが一覧表示されています。REST API のエラーページには、API が送るすべてのコードが一覧表示されています。
安全に再試行する
- 読み取りは、自由に再試行できます。
getやlistには、副作用がありません。 - 有料のリクエストを、むやみに繰り返さないでください。タイムアウトしたリクエストでも、実行はすでに始まっている場合があります。生成を再試行する前に、冪等性キーを渡してください。
client.nodes.run(type, params, { idempotencyKey })とrunAndWaitは、これを受け付けます。同じリクエストを再試行するときに同じキーを使うと、プラットフォームは 2 回目の実行を開始して課金する代わりに、最初の実行を返します。 - スタジオと Recast は、独自の再試行用トークンを使います。スタジオのメソッドでは
clientRequestId、client.recast.rescore()ではrequestIdです。 - 5xx の応答は、間を置いて再試行してください。
createClient内でのカスタムfetchは、そのための処理を置くのに適した場所です。
throwFromResponse(status, body)
throwFromResponse(status: number, body: {
error?: { code?: string; message?: string; [key: string]: unknown }
}): neverHTTP ステータスと Nodaro のエラーボディを、対応するエラークラスに変換してスローします。SDK はすべての応答でこれを使っており、クライアントを使わずに API を呼び出すカスタムのトランスポートのためにも、これはエクスポートされています。
プロパティ
型
import { throwFromResponse } from "@nodaro/sdk"
throwFromResponse(403, {
error: { code: "insufficient_scope", message: "Missing scope", missingScope: "workflows:execute" },
})
// throws a ForbiddenError whose missingScope is "workflows:execute"ほとんどのルートは { error: { code, message } } のエンベロープで応答します。一部の古いルートは別の形で応答しますが、SDK はそれらも読み取るので、エラーには実際の code と message が入ります。
| ボディ | code | message |
|---|---|---|
{ error: "<code>", message? }(キャラクターのトレーニングなど) | その文字列 | message。ない場合はコード |
{ error: "<code>", error_description }(OAuth) | その文字列 | error_description |
{ message, issues: [...] }(HTTP 400 の検証エラーの応答) | validation_error | message |
{ statusCode, error: "<reason phrase>", message }(サーバーにないルートなど) | internal_error | message |
HTTP 500 以上では、SDK はこれらの形からコードだけを読み取り、テキストは読み取りません。そのようなエラーの message は、そのコードか「Request failed」です。エンベロープ自体の message は、どのステータスでも読み取られます。
エラークラスは引き続きステータスで決まります。404 は、ボディの内容にかかわらず NotFoundError です。読み取れるテキストがないボディでは、「Not found」のようなクラスの既定のメッセージのままになります。InsufficientCreditsError は、required と available をエンベロープから、またはサーバーがその横に送る required と balance のフィールドから読み取ります。ユーザーごとの割り当ての場合、available は remaining から読み取られます。
よくある質問
TypeScript で、Nodaro API のエラーをキャッチするには、どうすればよいですか?
呼び出しを try/catch で囲み、instanceof でエラーを判定します。最も具体的なクラスから調べ、最後に NodaroError を調べてください。すべてのクラスは、@nodaro/sdk からエクスポートされています。
アカウントのクレジットが足りない場合、何が起きますか?
呼び出しは、処理が始まる前に、HTTP ステータス 402 の InsufficientCreditsError をスローします。その required と available フィールドで、実行に必要なクレジットの数と、アカウントが持つクレジットの数がわかります。
JobTimeoutError は、ジョブをキャンセルしますか?
いいえ。ジョブは実行を続け、たいていはそのまま完了します。後から client.jobs.get(jobId) で取得するか、遅いモデルには maxMs を大きくしてください。
RateLimitedError の後は、再試行すべきですか?
はい、少し待ってからです。数秒待ち、新しい 429 が出るたびに待ち時間を倍にし、何度か試したら止めてください。
ForbiddenError には、どのコードが入りますか?
サーバー自身のコードです。たとえば insufficient_scope や node_not_available なので、そのコードで分岐できます。サーバーがコードを送らなかった場合にだけ、code は forbidden になります。拒否されたモデルは ModelUnavailableError として、拒否されたリンクのインポートは ImportRefusedError として届きます。
関連ページ
TypeScript SDK
ジョブと実行
ノードの実行
エラー
レート制限
最終更新