NodaroAccount
Nodaro ドキュメント
ドキュメントノードリファレンスモデルテンプレートAI エージェント(MCP)開発者向けセルフホスティングリサーチ比較
TypeScript SDK

エラー

Nodaro の TypeScript SDK がスローするすべてのエラーを、HTTP ステータス、コード、フィールドとともに説明し、クレジット、レート制限、競合、失敗したジョブへの対処法も扱います。

Nodaro SDK が API の応答に対してスローするエラーは、すべて NodaroError かそのサブクラスのインスタンスです。エラーステータスで失敗したリクエストは、そのステータスに対応するサブクラスをスローします。run-and-wait のヘルパーは、ジョブが失敗、タイムアウト、停止したときに、それぞれ専用のサブクラスをスローします。具体的なクラスから先にキャッチし、NodaroError は最後にキャッチしてください。

すべてのエラークラス

クラスステータスcode追加のフィールドスローされる条件
NodaroErrorいずれかサーバー自身のコードです基底クラスで、より具体的なクラスがないすべてのエラーです
UnauthorizedError401unauthorizedトークンが未指定か、期限切れか、無効です
ForbiddenError403サーバーのコード、なければ forbiddenmissingScope?権限がない、または OAuth トークンにスコープが不足しています
ModelUnavailableError403model_not_available または model_disabled選んだモデルが提供されていない、または管理者がオフにしました
ImportRefusedError403imports_blocked、import_source_disabled、link_imports_disabled または rights_* コードリンクのインポートが、何かを取得する前に拒否されました
NotFoundError404サーバーのコード、なければ not_found項目が存在しない、またはあなたには見えません
RateLimitedError429サーバーのコード、なければ rate_limitedリクエストが多すぎます
InsufficientCreditsError402insufficient_credits、またはほかの 402 のコードrequired?、available?アカウントが、実行の料金を払えません
CreditCapExceededError402budget_exceeded、member_cap_exceeded、user_allowance_exceededrequired?、available?ほかの人が設定した支出の上限が、実行を拒否しました
StorageExceededError413storage_exceededlimitBytes?、reason?送ったものが収まりません。ストレージがいっぱいか、1 つのファイルが上限を超えています
WorkflowConflictError409workflow_conflict または production_busycurrentUpdatedAt?、currentVersion?、currentRecord?先に、ほかの人がその項目を変更しました
AlreadyRunningError409already_runningexecutionId開始または続行を求めた実行が、まだ進行中です
AppRunVersionChangedError409app_run_version_changedrunVersion?、appVersion?アプリのバージョンが変わったため、アプリの実行の再試行が拒否されました
JobBlockedError422job_blockedデプロイ環境のコンテンツポリシーが、リクエストを拒否しました
MediaTooLongError422media_too_long大容量アップロードのファイルが 30 分より長い
LargeUploadUnavailableError409 または 404large_upload_unavailable大容量アップロードのルートがないサーバーで、500 MB を超えるファイルを送った
StudioOpError4xxサーバー自身のコードですopIndexスタジオのバッチ内の 1 つの操作が、拒否されました
JobFailedError0job_failedjobId、jobStatus待っていたジョブが、失敗またはキャンセルされました
JobTimeoutError0job_timeoutjobId、timeoutMsジョブが maxMs 以内に終わりませんでした
JobAbortedError0job_abortedjobId?待っている間に、自分の AbortSignal が発火しました
JobHeldError0job_heldjobIdジョブが、人によるレビューのために保留されています
StudioPreviewUnavailable0studio_preview_unavailableデプロイ環境が、スタジオのバッチをプレビューできません
StudioPreviewAppliedError0studio_preview_appliedappliedプレビューを求めたスタジオのバッチが、適用されました

どのクラスにも、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_large1 つのファイルがサイズの上限を超えています。ストレージはいっぱいではありません。小さいファイルを送ってください。
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 を比較して処理してください。

ステータスコード対象意味
400validation_error多くのメソッドフィールドが不足しているか、無効です。message にその名前が示されます。
400no_valid_inputsclient.reduce.run()すべての入力が空でした。
400invalid_edlclient.edit.applyEdl()編集決定リストが、検証に失敗しました。
400limit_reachedclient.developerApps.create()すでにアプリの上限数に達しています。
400locked_fieldclient.apps.run()オーバーライドが、Webhook の URL など、送信先を変更しようとしました。
409name_takenキャラクター、組織名前またはスラッグが、すでに使われています。
409concurrent_modificationロケーション、オブジェクト読み取った後に、項目が変更されました。
410voice_cloning_retiredclient.voices.createClone()ボイスクローニングは、もう提供されていません。代わりにボイスデザインを使ってください。
400quote_unsupportedclient.nodes.quote()プラットフォームは、このノードタイプを見積もれません。メッセージに、見積もれるタイプが一覧表示されます。
400、502advanced_mode_unavailableclient.llm.structured()モデル自体のプロバイダーが、現在、詳細モードのリクエストを受け付けられません。モデルを実行するには、詳細モードをオフにしてください。
409job_cancelledclient.llm.structured() などの従量課金の LLM リクエストクレジットの確保後、呼び出しが送られる前にジョブがキャンセルされました。何も課金されません。ジョブは意図的にキャンセルされたものなので、そのまま再試行しないでください。
503job_start_failed従量課金の LLM リクエストサーバーが呼び出しの開始を記録できなかったため、呼び出しを送りませんでした。何も課金されません。再試行してください。
503provider_unavailableclient.llm.structuredJob()このインスタンスでは、このモデルを実行できません。再試行しないでください。
503feature_disabledclient.copilotこの機能は、このデプロイ環境ではオフになっています。
503nodaro_connection_requiredclient.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 }
}): never

HTTP ステータスと 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 が入ります。

ボディcodemessage
{ error: "<code>", message? }(キャラクターのトレーニングなど)その文字列message。ない場合はコード
{ error: "<code>", error_description }(OAuth)その文字列error_description
{ message, issues: [...] }(HTTP 400 の検証エラーの応答)validation_errormessage
{ statusCode, error: "<reason phrase>", message }(サーバーにないルートなど)internal_errormessage

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 として届きます。

最終更新

目次