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

エラー

Nodaro API のエラーは、HTTP ステータスと変更されないコードを 1 つのエンベロープで返します。各コードの意味、再試行すべきエラー、失敗したジョブが理由を伝える方法を説明します。

Nodaro API のエラーは、どれも HTTP ステータスと、変更されない code を含む 1 つの JSON エンベロープを返します。そのため、クライアントはメッセージを解析せずに、コードで処理を分岐できます。失敗には 2 種類あります。呼び出し自体が拒否されて何も開始されないリクエストエラーと、開始した生成が後から失敗し、その理由をジョブで報告するジョブの失敗です。

エラーエンベロープ

{ "error": { "code": "rate_limited", "message": "Too many requests. Max 30 per minute." } }
  • code は、変更されない識別子(スラッグ)です。処理の分岐には、この値を使います。
  • message は、人が読むためのテキストです。変わることがあるので、この値で照合しないでください。
  • エラーによっては、フィールドが追加されます。追加されるフィールドは、以下の各コードに記載しています。ほとんどは error の中に入りますが、already_running では executionId が error と同じ階層に置かれます。また、実行前の利用枠のチェックに失敗した場合は、required と remaining がトップレベルに入ります。

唯一の例外は OAuth のトークンエンドポイントで、OAuth の形式で応答します。たとえば { "error": "invalid_grant", "error_description": "…" } のような形式です。OAuth アプリを参照してください。

再試行すべきエラー

ステータス対処
5xx通常は一時的なエラーです。指数バックオフで再試行します。
429待ってから、バックオフしながら再試行します。たとえば、5 秒、10 秒、20 秒と待つ時間を延ばします。Retry-After ヘッダーがある場合は、その値に従ってください。
402クレジットを追加するか、ワークスペースの管理者に予算を依頼してから、再試行します。
その他の 4xxまずリクエストを修正します。同じリクエストは、再び失敗します。

次の 3 つのサーバーエラーには、注意が必要です。

  • 503 price_not_configured は、再試行しても成功しません。このデプロイ環境の運用者が料金を設定するまで、そのモデルには料金がないためです。
  • 非同期の構造化出力 LLM ルートでの 503 provider_unavailable は、言語モデルの呼び出しを nodaro.ai に送るセルフホスティング環境では、恒久的なエラーです。
  • SNS への投稿では、503 publish_retryable は何も投稿されていないことを示し、同じリクエストを安全に再送できます。一方、500 publish_failed は結果が不明であることを示し、再送すると二重に投稿されるおそれがあります。

エラーコード

400 Bad Request(不正なリクエスト)

コード意味
validation_errorリクエストボディの形式の誤り、不正な UUID、無効なフィールド、形式が正しくないカーソルのいずれかです。reason: "llm_model_unpriced" の場合は、まだ料金のない LLM のモデルです。まだ料金のないモデルを参照してください。
limit_reached有効か無効かにかかわらず、API トークンがすでに 10 個あります。先に 1 つ削除してください。
invalid_workflowトークンの workflowIds に含まれる値が、個人スペースにあるワークフローではありません。
token_workspace_mismatch1 つのワークスペースに紐付いたトークンが、別のワークスペースを指定する X-Nodaro-Workspace ヘッダーとともに送られました。
locked_field実行で、外部と通信するノードの送信先または取得元を変更しようとしました。実行で変更できないものを参照してください。
image_requiredテキストから動画を作れないモデルで、開始フレームを指定せずに POST /v1/generate-video を呼び出しました。代わりにリファレンスを使えるかどうかは、メッセージに示されます。
sequence_execution_required実行に、スタジオプロダクション API で生成する必要があるスタジオプロダクションのノードが含まれています。
not_workspace_scopedワークスペースに属していないワークフローの visibility を変更しました。
advanced_mode_unsupported直接呼び出しの経路がないモデルで、advancedMode: true を指定しました。
media_link_bad_host課金の前にメディアのリンクを測定するノードに、ホストが存在しないリンク、またはプライベートや予約済みのアドレスを指す(またはそこにリダイレクトする)リンクが渡されました。メッセージは、リンクを確認するか、公開ホストへのリンクを使うかファイルをアップロードするよう伝えます。何も確保されません。メディアのリンクを参照してください。
advanced_mode_unavailableモデル自体のプロバイダーがリクエストを受け付けられない間に、advancedMode: true を指定しました。課金はされません。モデルを実行するには、詳細モードをオフにしてください。同じコードが呼び出しの途中で 502 として返されることもあります。その場合、プロバイダーが試行に課金していなければ返還されます。
quote_unsupportedプラットフォームが見積もれないノードタイプで POST /v1/quote を呼び出しました。メッセージに、見積もれるタイプが一覧表示されます。実行の見積もりを参照してください。
continuation_subset_requirednodeIds も continueMode もなしで continueFromExecutionId を指定しました。実行を続けるを参照してください。
continuation_workflow_mismatchcontinueFromExecutionId で指定した実行は、別のワークフローの実行です。
continuation_version_mismatchcontinueFromExecutionId で指定した実行は、ワークフローの公開アプリバージョンの実行です。
render_final_node_not_foundrenderFinal.renderNodeId が、ワークフローのどのノードも指していません。
media_unreadableエピソードを引き締める、チャプター、トレーラー、クリップパック、スピーカーレイアウトなどのユースケースの実行で、録音を読み取れませんでした。リンクが開けること、動画または音声のファイルであることを確認してください。何も作成も課金もされません。
media_has_no_audioユースケースの実行またはその見積もりで、録音に書き起こす音声がありません。メッセージがその録音を示します。何も作成も課金もされません。
media_too_longユースケースの実行またはその見積もりで、録音またはマスターオーディオが 3 時間を超えています。メッセージがどちらかを示します。何も作成も課金もされません。
master_audio_unreadablemasterAudioUrl を指定したユースケースの実行またはその見積もりで、マスターオーディオを音声として読み取れませんでした。何も作成も課金もされません。
render_final_not_a_renderrenderFinal.renderNodeId が、EDL 適用のレンダリングではないノードを指しています。
suno_cover_sourcetaskId と audioId を付けた POST /v1/suno/cover で、ID ではカバーできず、uploadUrl もありません。たとえば、自分の完成した曲ではないタスク、曲のトラックではない audioId、ID によるカバーでは使えない設定です。代わりにオーディオを uploadUrl として渡してください。クレジットはかかりません。Suno カバーを参照してください。
suno_wav_stem変換できないステムに対する Suno の WAV 変換です。分離結果に Suno のステムがない、ステムの ID が残っていない、または audioId がそのステムではありません。ID が残っていない場合は、分離をもう一度実行してください。クレジットはかかりません。Suno WAV 変換を参照してください。
suno_not_a_trackPOST /v1/suno/convert-wav、/v1/suno/extend、/v1/suno/separate で、Suno スピーチのテイクを Suno の ID で指定しました。話し声のテイクは曲ではありません。クレジットはかかりません。ルートが URL を受け付ける場合は、オーディオを URL で渡してください。
media_link_not_a_fileメディアのリンクが、.m3u8 や .mpd のようなストリーミングのプレイリストやマニフェスト、または GIF のようにサーバーが読み込めない形式を指しています。代わりにファイルをアップロードしてください。何も課金されません。メディアのリンクを参照してください。

401 Unauthorized(認証されていない)

コード意味
unauthorizedトークンが指定されていないか、無効、期限切れ、または取り消し済みです。

402 Payment Required(支払いが必要)

これらのコードは、Nodaro Cloud と、課金を行うデプロイ環境から返されます。

コード追加フィールド意味
insufficient_creditsrequired、balanceアカウントのクレジットが足りません。1 つの請求アカウントが全員分を支払うデプロイ環境では、デプロイ環境のプールが空であることを意味します。その場合、エラーには required が含まれますが、balance は含まれません。また、クレジットを追加できるのは請求アカウントだけです。ポッドキャストのユースケースの実行とその続行(POST /v1/tighten-episode、/v1/episode-chapters、/v1/episode-trailer、/v1/clip-pack、/v1/speaker-layout と、それぞれの /continue)は、何かを始める前に、実行するすべての見積もりと残高を照合します。その拒否には estimate: true が加わります。このとき required は実行の料金ではなく見積もりで、実行には実際に使った分が課金されます。
insufficient_app_credits公開アプリの実行で、アカウントのクレジットが足りません。
budget_exceededワークスペースが支払う処理で、ワークスペースの予算では実行をまかなえません。ワークスペースの管理者に追加を依頼してください。
member_cap_exceededワークスペースが支払う処理で、そのワークスペースでの自分の利用上限に達しました。
user_allowance_exceededrequired、remainingユーザーごとの利用枠を適用している、1 つの請求アカウントが全員分を支払うデプロイ環境で、自分の利用枠では実行をまかなえません。利用枠を引き上げられるのは、請求アカウントだけです。
instance_cap_reached接続済みのセルフホスティング環境の OAuth トークンで、その環境が、接続元のアカウントに設定された月間上限を使い切りました。接続済みのインスタンスで、上限を引き上げるか解除してください。

403 Forbidden(アクセス禁止)

コード追加フィールド意味
forbiddenトークンにワークフロースコープがあり、リクエストがその範囲外です。または、このルートにはログイン済みのセッションが必要です。トークンを一部のワークフローに限定するとログイン中のセッションが必要なルートを参照してください。
access_blockedNodaro Cloud と Business エディションで、管理者がアカウントをブロックしました。セッション、API トークン、OAuth トークンなど、アカウントのすべての認証情報が拒否されます。アカウントのスケジュールとトリガーは止まり、公開アプリには 404 not_found が返されます。誤りだと思われる場合は、サポートにお問い合わせください。
insufficient_scopemissingScopeOAuth トークンに、ルートに必要なスコープがありません。より広いスコープを指定して、ユーザーにもう一度同意画面を通ってもらってください。
mcp_client_not_allowedデプロイメントが MCP を使えるクライアントを指定していて、このクライアントまたはトークンがそれに含まれていません。MCP クライアントを指定するデプロイメントを参照してください。
developer_apps_admin_onlyこのデプロイメントでは、開発者アプリの作成、変更、削除、シークレットのローテーションができるのは管理者だけです。自分のアプリの読み取りは引き続きできます。
in_app_onlyこのルートは、ワークフロー Copilot など、Nodaro の Web アプリ専用です。
node_not_availableこのデプロイ環境では、そのノード、またはノードで選んだオプションを、あなたのアカウントに提供していません。メッセージにその名前が示されます。料金は発生しません。課金されるすべてのルートは、パスに関係なく、実行するノードとして確認されます:POST /v1/suno/generate は suno-generate として、トレンドの実行(POST /v1/trends/:slug/runs とその /estimate)は Video Remake の cast-swap として、POST /v1/video-director/run は動画ディレクターの video-director として、POST /v1/pipelines と、作業を開始または続行するパイプラインのルートは映画パイプラインの film-pipeline として確認されます。パイプラインを参照してください。
suno_task_not_yoursPOST /v1/suno/cover が、別のアカウントの実行で作られた taskId を指定し、uploadUrl がありません。クレジットはかかりません。uploadUrl があれば、いつもどおりそのファイルをカバーします。
model_not_availableリクエストが、このデプロイ環境で提供していないモデルで実行されることになります。対象は、指定したモデルです。モデルを制限しているデプロイ環境では、何も指定しないときにルートが使うデフォルトも対象です。画像ではアスペクト比ごとのデフォルト、機能ではデフォルトの言語モデル、ルートでは固定の 1 つのモデルです。何も作成も課金もされません。GET /v1/models が記載するモデルを指定してください。
model_disabledNodaro Cloud のみです。管理者がこのモデルをオフにしています。クレジットは確保されず、料金も発生しません。クレジットを購入しても解決しません。別のモデルを選ぶか、モデルが再びオンになってからもう一度お試しください。
edition_requiredrequired_editionこのルートには、より上位のエディションが必要です。パイプラインの分岐には cloud、API トークンの管理には business が必要です。
not_a_memberX-Nodaro-Workspace ヘッダーが、自分がアクティブなメンバーではないワークスペースを指定しています。
member_suspendedワークスペースでの自分のメンバーシップが停止されています。
personal_space_disabled組織の設定により、ワークスペースの中でしか作成できません。ワークスペースのヘッダーを送ってください。
project_create_not_allowedプロジェクトを作成できるのは、ワークスペースの管理者だけです。
workspace_archivedワークフローの共有など、アーカイブ済みのワークスペースへの書き込みです。そこで新たに作成しようとした場合は、代わりに 409 が返ります。
not_permittedこのワークフローを移動する権限がないか、その場所に移動する権限がありません。
sso_requiredデプロイ環境がログインを自身の ID プロバイダーに限定しており、このセッションのアカウントは、その ID プロバイダーを通じて作成されていません。トークンには影響しません。
subscription_required従量課金のアカウントが、Web エディターからクレジットを使おうとしました。従量課金のクレジットは API、SDK、CLI、MCP で使えるため、トークンでの呼び出しがこのコードを受け取ることはありません。
api_tokens_payer_only1 つの請求アカウントが全員分を支払うデプロイ環境では、API トークンを作成できるのは、その請求アカウントだけです。
payer_balance_jwt_onlyそのようなデプロイ環境で、請求アカウントがトークンを使ってプールの残高を読み取りました。残高を読み取れるのは、請求アカウント自身のブラウザーセッションだけです。
payer_requiredデプロイ環境の請求用のルートが、請求アカウントのブラウザーセッション以外から呼び出されました。
rights_confirmation_required、rights_authorization_required、およびその他の rights_confirmation_* コードリンクのインポートに、当てはまるコンテンツ権利の確認がありません。何も取得されていません。コンテンツ権利を参照してください。
import_source_disabledデプロイ環境が、リンク先のサイトからのインポートを許可していません。
link_imports_disabledこのデプロイ環境は、ほかのサイトへのリンクからのインポートをオフにしています。代わりにファイルをアップロードしてください。デプロイ環境自身のストレージのファイルは拒否されません。コンテンツ権利を参照してください。
imports_blockedデプロイ環境の繰り返し侵害者ポリシーにより、アカウントでリンクのインポートがブロックされているか、アカウントが閉鎖されています。メッセージには、いつまでかが示されます。繰り返し侵害者を参照してください。

404 Not Found(見つからない)

コード意味
not_foundリソースが存在しないか、あなたには見えません。ID から存在の有無がわからないように、どちらの場合も意図的に同じレスポンスを返します。
workspace_not_foundワークスペースが支払う処理で、存在しないワークスペースが指定されました。
continuation_not_foundcontinueFromExecutionId で指定した実行が存在しないか、あなたのものではありません。
checkout_session_not_foundCheckout セッションの読み取り、または replacesSessionId が、自分のものではない、存在しない、または同じ購入のものではないセッションを指定しています。以前の Checkout セッションを置き換えるを参照してください。

409 Conflict(競合)

コード追加フィールド意味
already_runningexecutionIdこのワークフローは、すでに実行中です。または、アプリの実行の再試行が保留中です。代わりに、その実行をポーリングしてください。
continuation_not_completedcontinueFromExecutionId で指定した実行が、まだ進行中か、失敗したか、キャンセルされました。continueMode なしで続けられるのは、完了した実行だけです。
continuation_not_failed"continueMode": "from-failed" の場合:実行が失敗していません。
continuation_supersededexecutionId、supersededBy"continueMode": "from-failed" の場合:その実行のより新しい続行が失敗したため、そちらを続けてください。または、その続行が残りをすべて完了しています。失敗した実行を続けるを参照してください。
continuation_preview_pendingexecutionId、renderNodeIds、reviewNodeIds、next"continueMode": "from-failed" の場合:最新の続行がプレビューのレビューで止まっています。先に、next を実行の本文として送ってください。
continuation_subset_required"continueMode": "from-failed" の場合:続ける対象が何も残っていません。アプリの実行の再試行の場合:すべてのステップが完了しています。
app_run_version_changedappVersion、runVersion別のアプリバージョンで行われたアプリ実行の再試行です。実行を最初からやり直してください。
app_run_version_unavailableバージョンが利用できなくなったアプリ実行の再試行です。実行を最初からやり直してください。
workflow_conflictcurrentVersion、currentUpdatedAt、currentRecord送ったバージョンの後に、ワークフローが変更されました。currentRecord に変更をマージして、もう一度保存してください。
job_cancelled同期的な従量課金の LLM リクエストで、クレジットの確保後、呼び出しが送られる前にジョブがキャンセルされました。従量課金の LLM リクエストを参照してください。
idempotency_key_reused—エピソードを引き締めるの実行またはその続行(POST /v1/tighten-episode、POST /v1/tighten-episode/continue)で、Idempotency-Key が、画像生成など、あなたの別の種類のジョブにすでに使われています。何も作成も請求もされません。新しいキーを送ってください。同じノードの実行に使われているキーには、その実行が 202 と "deduped": true で返ります。
batch_in_progressバッチルート(count または models を指定した画像のバッチ、count が 2 以上の /v1/generate-character、/v1/generate-creature、/v1/generate-location、/v1/generate-object、または versions が 2 以上の /v1/video-sfx)が、別のリクエストがまだバッチを作成している間に、同じ Idempotency-Key の 2 つ目のリクエストを受け取りました。それ以上は何も作成も請求もされていません。少し待ってから再試行してください。同じジョブが返ります。
workspace_archivedアーカイブ済みのワークスペースで作成しようとしたか、そこへ移動しようとしました。
workspace_has_no_default_projectワークスペースでの作成でプロジェクトが指定されておらず、そのワークスペースにはデフォルトのプロジェクトもありません。プロジェクトを指定してください。
move_blocked課題のために作成されたものなので、移動できません。
production_capability_required汎用のワークフロー保存で、専用の API で扱う必要があるスタジオプロダクションを変更しようとしました。
retained_image_in_use削除すると保護された画像が消えてしまうか、プロダクションにまだその画像を使っているジョブがあります。先にそれらのジョブを完了させるか、キャンセルしてください。
content_heldファイルが申し立ての証拠として保全されているため、現在は削除できません。制限されたコンテンツを参照してください。
large_upload_unavailableデプロイメントがすべてのアップロードのバイトを確認しているため、大容量アップロードのルートは閉じられています。500 MB までのファイルを POST /v1/upload で送ってください。大容量の動画やオーディオをアップロードするを参照してください。
checkout_already_complete、checkout_in_progressreplacesSessionId を付けた Checkout のリクエストで、以前のセッションがすでに支払い済みか、その支払いがまだ確認中です。以前の Checkout セッションを置き換えるを参照してください。
not_applicable1 つの請求アカウントがすべてのユーザーの分を支払うデプロイ環境での、無料の登録クレジットのルート:POST /v1/credits/claim-signup-grant と 2 つのウェルカムオファーのルートです。そこでは無料の登録クレジットは適用されないので、何も記録も付与もされません。再試行することはなく、ページを読み込むたびに申請するクライアントは無視してかまいません。

413、422、429、451

ステータスコード意味
413アカウントがストレージの上限を超えています。SDK は StorageExceededError をスローします。
422job_blockedデプロイ環境のジョブポリシーまたはコンテンツガードが、実行前に生成を拒否しました。ジョブは作成されず、何も課金されていません。message をそのままユーザーに表示し、同じリクエストを再試行しないでください。
422upload_blockedデプロイ環境のアップロードポリシーが、保存前にファイルを拒否しました。message をそのまま表示してください。
422idempotency_key_reusedバッチルートの Idempotency-Key が、すでに別のリクエストに使われています。別のルートのジョブか、同じルートで本文が違うリクエストのジョブで、そのどれかがまだ待機中の場合です。何も作成も請求もされません。同じリクエストをもう一度送るか、新しいキーを使ってください。
422media_too_longファイルが、エディターに取り込めるメディアの上限である 30 分より長いです。大容量アップロードの complete、または POST /v1/download-video の動画への直接リンクで発生します。何も残されず、ストレージの使用量にも数えられません。
422media_too_largeファイルが 10 GiB を超えています。大容量アップロードの start、または POST /v1/download-video の動画への直接リンクで発生します。
422media_bitrate_implausibleファイルが、その長さに対して大きすぎます。最初の 16 MiB を除いた平均で、動画が 2,500 Mbit/s、オーディオが 50 Mbit/s を超えています。
422offsets_not_appliedPOST /v1/edit-plan が、生の offsets フィールドを受け取りました。先に、各オフセットを sources[].offsetMs としてそれぞれのソースに書き込んでください。編集プランを参照してください。
422master_offsetPOST /v1/edit-plan が、マスター、または文字起こしの元になったソースに、0 以外のオフセットを受け取りました。料金は発生しません。
429rate_limited個人用 API トークンの、トークンごとの制限です。
429rate_limit_exceededそれ以外の制限です。アドレスごと、ルートごとの制限や、公開アプリの 1 日あたりの実行回数の制限が該当します。
429too_many_downloadsすでに 4 件の動画のインポートが実行中です。
429too_many_open_uploads大容量アップロードが、すでに 3 件開いています。1 件を完了するか中止してください。放置されたアップロードは、トークンの期限が切れると枠を空けます。
451content_restrictedGET /v1/download または GET /v1/image-proxy に、Nodaro が制限したファイルが要求されました。制限されたコンテンツを参照してください。

job_blocked と upload_blocked は、そのようなポリシーを登録したデプロイ環境でのみ発生します。429 のコードについては、レート制限を参照してください。

500、503

ステータスコード意味
500internal_errorサーバーエラー、またはサーバーが依存するサービスの障害です。バックオフしながら再試行してください。ジョブまたは実行を開始のキューに入れられなかった場合、それはすぐに失敗となり、クレジットは返還され、Idempotency-Key は解放されます。そのため、同じキーで再試行すると新しいジョブまたは実行が始まります。ジョブの一部だけが開始したバッチでは、実行中のジョブが error.startedJobIds に示されます。それらを追跡し、同じキーで同じリクエストをもう一度送ると、残りだけが開始されます。
502advanced_mode_unavailable詳細モードの LLM 呼び出しが、途中でモデル自体のプロバイダーに拒否されました。プロバイダーが試行に課金していなければ、確保額は返還されます。モデルを実行するには、詳細モードをオフにしてください。
503provider_key_missing書き起こしを行うユースケースの実行またはその見積もりで、セルフホストのインストールに、その書き起こしプロバイダーのキーも、それを補う Nodaro Cloud への接続もありません。メッセージがキーを示します。何も作成されません。
503job_start_failed同期的な従量課金の LLM リクエストで、呼び出しの開始を記録できませんでした。従量課金の LLM リクエストを参照してください。
503price_not_configuredこのデプロイ環境では、リクエストしたモデルに料金が設定されていません。誤った金額で課金しないよう、サーバーはリクエストを拒否します。再試行しても解決しません。
503rate_limit_unavailableクレジットを消費するルートが、レート制限を確認できませんでした。しばらくしてから再試行してください。
503source_unreachable、probe_timeout、probe_unavailable課金の前にメディアのリンクを読み込めませんでした。ホストを名前解決できなかった、読み込みが時間切れになった、またはその時点でサーバーが読み込みを実行できなかった、のいずれかです。何も課金されません。リクエストをもう一度実行してください。メディアのリンクを参照してください。
503provider_unavailableモデルのプロバイダーが利用できません。
503embedded_checkout_unavailableページ内の支払いフォームがないデプロイメントで、uiMode: "embedded" を付けた Checkout のリクエストを送りました。代わりに Checkout のページに案内してください。
503billing_unavailableこのインスタンスでは使用量の報告を利用できないか、アプリの再試行のワークスペースでの実行で、課金が一時的に利用できません。少し待ってから、もう一度お試しください。

従量課金の LLM リクエスト

言語モデルの呼び出しは、使ったトークンに応じて課金されるため、呼び出しが始まる前にクレジットが確保されます。テキスト生成、プロンプトヘルパー、POST /v1/llm/structured など、この種類の同期的なリクエストは、さらに 2 つのコードを返すことがあります。

  • 409 job_cancelled:クレジットの確保後、呼び出しが送られる前にジョブがキャンセルされました。呼び出しは送られず、確保額は返還されます。ジョブは意図的にキャンセルされたものなので、リクエストをそのまま再試行しないでください。
  • 503 job_start_failed:サーバーが呼び出しの開始を記録できなかったため、呼び出しを送りませんでした。確保額は返還されます。リクエストを再試行してください。

まだ料金のないモデル

LLM ノードは、モデルごとに、それを処理する経路の単価で課金されます。その経路に単価のないモデルは実行できません。そのモデルの料金を出したり実行したりするルートは、すべて 400 を返します。

{
  "error": {
    "code": "validation_error",
    "reason": "llm_model_unpriced",
    "modelId": "<model>",
    "message": "The model \"<model>\" has no price yet, so it cannot be run. Choose another model."
  }
}
  • 見積もり:POST /v1/credits/estimate-workflow、GET /v1/credits/model-cost、POST /v1/component/estimate-credits、POST /v1/workflows/:id/render-final/estimate、各ユースケースノードの /estimate ルートです。POST /v1/credits/model-costs は、代わりにキーごとに答えます。そのキーを errors に一覧表示し、errorCodes のエントリーを付けます。
  • 公開:POST /v1/apps/publish と POST /v1/templates/publish は、何かが書き込まれる前に拒否します。再公開の場合、現在のバージョンが公開されたままになります。
  • 実行:POST /v1/workflows/:id/run、POST /v1/app/:slug/run、POST /v1/app/:slug/runs/:runId/resume、POST /v1/component/execute、POST /v1/api/run、POST /v1/present/:token/run、各ユースケースノードの実行と続行のルートです。確認は、入力の上書きを適用したうえで、実行が作成される前に行われます。どのノードも実行されないので、何も課金されません。MCP ツールの run_app、run_workflow、run_component も同じルートに届きます。
  • トリガー:Webhook の起動には、同じ 400 が返ります。スケジュール、Telegram、プラグインのトリガーの起動は、スキップされます。各トリガーは、ワークフローの履歴に、error_message: "llm_model_unpriced" の失敗した実行を 1 つ残します。繰り返し起動しても、それ以上は増えません。
  • 実行の中:サーバーは、実行が始まるとき、どのノードも実行される前に、もう一度確認します。この確認は、実行するサブワークフローとコンポーネントも対象にします。ここで拒否された実行は failed で終わり、上のメッセージがその error_message になります。サブワークフローの中のモデルでは Found inside Sub-workflow node <id>. が、コンポーネントの中のモデルでは Found inside Component node <id>. が加わります。

読み取り専用の 2 つのルートは、引き続きワークフローを説明します。GET /v1/present/:token は estimatedCost を省き、estimatedCostUnpriced: { reason, modelId, message } を返します。GET /v1/api/schema は estimatedCredits を省き、同じ形の estimatedCreditsUnpriced を返します。

ジョブが後から失敗した場合

リクエストが成功しても、作成されたジョブが失敗することがあります。その場合、ジョブには error_message が含まれ、5 種類の失敗では、構造化された error_hint も含まれます。

  • モデルの安全フィルターがリクエストをブロックした場合は、{ "kind": "safety-block", "class": "copyright" | "likeness" | "safety", "retried": boolean, "suggestedProvider"?: string, "subject"?: "input_video" | "input_image" | "prompt" | "audio" } です。subject: "input_video" は、プロバイダーがジョブの入力動画そのものを拒否したことを意味するので、別のクリップを送ってください。subject: "input_image" は常に class: "copyright" と一緒に返され、プロバイダーがジョブの入力画像のいずれかを、著作権で保護されている可能性があるとして拒否したことを意味します。プロンプトを言い換えても解決しないので、別の画像を送ってください。subject: "prompt" は、プロバイダー自身の文面がプロンプトを原因として挙げたことを意味するので、プロンプトを変えてください。subject: "audio" は、プロバイダー自身の文面が、画像ではなく生成されたオーディオを原因としたことを意味します。知らない subject は、ないものとして扱ってください。
  • デプロイ環境のポリシーがリクエストを拒否した場合は、{ "kind": "policy-block", "policyId": string, "reason": string, "hookPoint": "request" | "result" } です。
  • ジョブが途中でクレジット不足になった場合は、{ "kind": "credits", "code": string } です。たとえば insufficient_credits や、budget_exceeded などのワークスペースの上限です。
  • プロバイダーが、コンテンツポリシーの分類を示さずにジョブの入力動画を拒否した場合は、{ "kind": "input-refused", "subject": "input_video" } です。ほかのモデルは提案されません。別のクリップを送ってください。
  • プロバイダーが、送られたままのリクエストを拒否し、その不備(設定、ファイルの形式やサイズ、プロンプトの長さ)を示した場合は、{ "kind": "request-refused", "subject"?: "input_video" } です。同じリクエストはまた拒否されるので、入力画像、動画、プロンプト、または設定を変えてください。subject: "input_video" は、長さやサイズ、キャラクターが見つからないなど、プロバイダーの文面が入力動画を不備として挙げた場合に含まれます。別のクリップを送ってください。コンテンツポリシーによるブロックではありません。

失敗したジョブには、プロバイダー自身の言葉である error_detail、または null も含まれます。この言葉は、実行のワークフローを開ける呼び出し元にだけ届きます。デプロイメントは、この言葉を管理者だけに限定することもできます。プロバイダー自身の言葉を参照してください。

最初の 3 つはクレジットが返還され、そのことはジョブの credit_status で確認できます。例外は失敗した従量課金の LLM 呼び出しで、プロバイダーが課金した使用分は請求されます。各フィールドの意味と、別のモデルを試すべき場合については、ジョブが失敗した理由を参照してください。

SDK でのエラー

@nodaro/sdk は、失敗したレスポンスごとに型付きのエラーをスローします。最も具体的なクラスから順に捕捉してください。

クラスステータス追加フィールド
UnauthorizedError401
ForbiddenError403コードが insufficient_scope の場合は missingScope
ModelUnavailableError403model_not_available と model_disabled 用の ForbiddenError のサブクラスです。拒否されているのは呼び出し元ではなく、モデルです。
NotFoundError404
InsufficientCreditsError402required、available。code は、その拒否自体の 402 のコードです。
CreditCapExceededError402budget_exceeded、member_cap_exceeded、user_allowance_exceeded 用の InsufficientCreditsError のサブクラスです。ほかの人が設定した上限です。
StorageExceededError413reason。reason は、ストレージがいっぱいの場合は storage_limit_exceeded、1 つのファイルが上限を超えた場合は file_too_large です。
WorkflowConflictError409currentVersion、currentUpdatedAt、currentRecord。スタジオの production_busy の競合にも使われます。
AlreadyRunningError409executionId:実行中の実行。already_running の場合
AppRunVersionChangedError409runVersion、appVersion。app_run_version_changed の場合
RateLimitedError429
JobBlockedError422
StudioOpError4xxopIndex:スタジオのバッチのうち、拒否された操作の位置
NodaroErrorすべて基底クラス:code、status、message、details(エンベロープのほかのフィールド)
import {
  NodaroError,
  ForbiddenError,
  InsufficientCreditsError,
  RateLimitedError,
} from '@nodaro/sdk'

try {
  await client.workflows.run(workflowId)
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    showPaywall({ required: err.required, available: err.available })
  } else if (err instanceof ForbiddenError && err.missingScope) {
    requestConsent([err.missingScope])
  } else if (err instanceof RateLimitedError) {
    await new Promise((r) => setTimeout(r, 5_000))
  } else if (err instanceof NodaroError) {
    console.error(`API error ${err.status} (${err.code}): ${err.message}`)
  } else {
    throw err // a network failure, not an API error
  }
}

ポーリング用のヘルパーは、JobFailedError や JobTimeoutError など、独自のエラーも追加します。単体のノードを実行するを参照してください。

CLI でのエラー

終了コード意味
0成功です。
1認証の失敗、リソースが見つからない、引数の誤り、ネットワークエラーのいずれかです。
2--watch が終了し、実行は失敗しました。
3ジョブがレビューのために保留されたため、--watch が停止しました。失敗ではありません。後で確認してください。
130--watch が終了し、実行はキャンセルされました。

--json を付けると、CLI はコード 2、3、130 を使わずに、ペイロードを出力して正常終了します。そのため、.status を自分で確認してください。

よくある質問

Nodaro API のエラーは、どのような形式ですか?

すべてのエラーは、HTTP ステータスと、{ "error": { "code": "…", "message": "…" } } という本文を返します。code は変更されないので、処理の分岐には code を使います。message は人が読むためのもので、変わることがあります。

Nodaro API のどのエラーを再試行すればよいですか?

5xx エラーと 429 は、指数バックオフで再試行します。たとえば、5 秒後、10 秒後、20 秒後です。4xx エラーは、同じリクエストが再び失敗するので、リクエストを変更せずに再試行しないでください。サーバーエラーのうち、503 price_not_configured は例外です。

402 insufficient_credits は、どういう意味ですか?

アカウントに、実行を開始するのに十分なクレジットがありません。エラーには、実行に必要なクレジットを示す required と、通常は balance が含まれます。Nodaro Cloud でクレジットを追加してから、リクエストをもう一度送ってください。

失敗したジョブの error_hint とは何ですか?

モデルの安全フィルター、デプロイ環境のポリシー、途中でのクレジット不足、拒否された入力動画、送られたままの形でプロバイダーに拒否されたリクエストという 5 種類の失敗について、失敗したジョブに付く構造化された理由です。error_message を解析する代わりに、この値を読み取ってください。たとえば、提案されたモデルをユーザーに示すときに使います。

llm_model_unpriced とはどういう意味ですか?

ワークフローやリクエストが指定した LLM のモデルに、実行される経路でまだ料金がないため、実行できないという意味です。応答は、reason が llm_model_unpriced で modelId を含む 400 validation_error です。別のモデルを選んでください。何も課金されません。

ルートが 403 in_app_only を返すのはなぜですか?

そのルートが、Nodaro の Web アプリ自身のセッション専用だからです。たとえば、ワークフロー Copilot や、Webhook 出力ノードの保存済みの認証情報がそうです。API トークンや OAuth トークンでは呼び出せません。代わりに、ワークフローのエンドポイント、SDK、MCP を使ってください。

最終更新

目次