エラー

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 アプリを参照してください。

再試行すべきエラー

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

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

エラーコード

400 Bad Request

401 Unauthorized

402 Payment Required

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

403 Forbidden

404 Not Found

409 Conflict

413、422、429

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

500、503

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

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

• モデルの安全フィルターがリクエストをブロックした場合は、{ "kind": "safety-block", "class": "copyright" | "likeness" | "safety", "retried": boolean, "suggestedProvider"?: string } です。
• デプロイ環境のポリシーがリクエストを拒否した場合は、{ "kind": "policy-block", "policyId": string, "reason": string, "hookPoint": "request" | "result" } です。

どちらの場合もクレジットは必ず返還され、そのことはジョブの credit_status で確認できます。各フィールドの意味と、別のモデルを試すべき場合については、ジョブが失敗した理由を参照してください。

SDK でのエラー

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

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 でのエラー

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