はじめに

エラー

すべての失敗は標準のHTTPステータスコードと共通のJSONエンベロープを返します。ほかを読む前に、まずsuccessで分岐してください。

失敗は2種類 リクエストエラー(不正なキー、不正なパラメータ、クォータ超過)は、下記のエンベロープを含む非2xx応答として同期的に返されます。生成失敗は後から発生します。生成リクエストは200を返しますが、その後アセットがtaskStatus: 3で終わり、消費したクレジットは自動的に返金されます。理由を確認するには、アセットのerrorCategory / errorDetailを読んでください。非同期とポーリングを参照してください。

エラーエンベロープ

error response
{
  "success": false,
  "error": {
    "code": 14001,
    "message": "Insufficient credit",
    "httpStatus": 402,
    "timestamp": "2026-08-05T09:12:00.000Z",
    "path": "/v1/models/from-text"
  }
}

エラー応答にはdataがありません。error.codeは安定した数値の識別子です。人間向けで変わる可能性があるerror.messageではなく、この値で分岐してください。

一部のコードに付くerror.details 一部のエラーは、失敗の背後にあるリアルタイムの数値を含むerror.detailsオブジェクトを返します。例: 13002は{ "total": 15, "maxTotal": 15 }を、14001は{ "required": 240, "available": 45, "topUpUrl": "https://picoberry.ai/pricing" }を返します。上限をクライアントにハードコーディングせず、これらの値を読んでください。

HTTPステータスコード

ステータス意味
400検証エラー。不正または欠落したパラメータ、非対応のエンジン/フォーマット、または読み取れない画像。
401APIキーが欠落、無効、または失効しています。
402ジョブを処理するにはクレジットが不足しています。
403アカウントにAPIの利用権限がありません。有効なサブスクリプションも完了したクレジット購入もありません。キーが1日の安全上限を超えて一時停止された場合（6016）や、無料アカウントが有料専用モデルを指定した場合（6017）にも返ります。
404アセットまたはコレクションが見つからないか、キーの所有ではありません。
413アップロードしたファイルが20 MBを超えました。
429レート制限(10003)、同時生成数の超過(13002)、またはアップストリームエンジンのクォータ超過です。バックオフしてから再試行してください。
500 · 503 · 504サーバーエラー、メンテナンス、またはアップストリームエンジンのタイムアウト。バックオフしながら再試行してください。

エラーコードカタログ

/v1で最も遭遇しやすいコードです。数値のcodeはリリース間で安定して維持されます。

コードHTTP発生する状況
1001401APIキーが欠落、無効、または失効しています。
6014403アカウントに有効なサブスクリプションも完了したクレジット購入もありません。APIの利用権限がありません。
60164031日の安全上限を超えたため、キーが自動で一時停止されました。アカウントの所有者がダッシュボードで再開するまで、使えるのは結果の確認とダウンロードだけです。再試行しないでください。
6017403無料アカウントが有料専用モデル（GET /v1/modelsでpaidOnly: true）を指定しました。キーはそのまま使えます。paidOnly: falseのモデルに切り替えるか、error.details.upgradeUrlから有料プランにアップグレードしてください。モデル（model・engine）を省略すると、プランで使えるモデルが既定で選ばれます。ただし、UV展開はすべてのエンジンが有料専用です。
14001402ウォレット残高でジョブを処理できません。error.detailsには、必要な量(required)、ウォレットからこのジョブに使える量(available)、追加先(topUpUrl)が入っています。追加するまでは再試行せず、GET /v1/creditsを確認してください。
2001400フィールドが検証に失敗しました(型、範囲、または長さ)。
2012400プロンプトまたは画像がコンテンツポリシーにより拒否されました。
7002413アップロードが20 MBの上限を超えました。
7003400非対応のアップロード形式です。
13001404不明なアセットidか、アセットがキーの所有ではありません。
13005400リメッシュのソースはAIで生成したモデルである必要があります。アップロードしたファイルはリメッシュできません。
13008400アニメーションのソースはリギングできません。明確な人型または動物型の形状が必要です。
10003429IPあたりまたはユーザーあたりのレート制限を超えました。
13002429進行中の生成が多すぎます。同時実行の上限を参照してください。課金はされないので、スロットが空いたら再試行してください。
20001504生成エンジンがタイムアウトしました。再試行しても安全です。
20002429エンジンの処理能力が一時的にいっぱいです。少し待ってから再試行してください。
20004400エンジンが入力を拒否しました(例: 処理できない画像)。

対処方法