エラーレスポンスはすべて同じ形式です。ステータスコード + 機械可読な code + 人が読めるメッセージ + 問題のある入力を示す任意の field。
{
"success": false,
"error": "Content length (5000) exceeds maximum allowed (4296 characters).",
"code": "CONTENT_TOO_LONG",
"field": "content"
}
| ステータス | 意味 |
|---|
200 | 成功 |
400 | 検証エラー — 入力を修正して再試行してください |
401 | 認証ヘッダーがない、または誤っている |
402 | ユーザーキーのゲートウェイ: Studio プランがないか、API クレジットを使い切っています |
404 | エンドポイントが見つからない |
413 | ボディが大きすぎる（10 MB超）、またはユーザーキーのゲートウェイ経由で生成ファイルが 10 MB を超えた（output_too_large） |
422 | 自動修正後もエンジンが読み取り可能なQRを生成できなかった（QR_UNSCANNABLE）、または出力が上限を超える（OUTPUT_TOO_COMPLEX） |
429 | レート制限 — Retry-After を参照 |
500 | 内部エラー — ログを記録して再試行 |
503 | サーバーが混雑している（大量の同時レンダリング）、または AI プロバイダーの容量が尽きた（AI_QUOTA_EXCEEDED） |
| コード | 意味 |
|---|
MISSING_REQUIRED_FIELD | content（AIエンドポイントでは prompt）が空 |
CONTENT_TOO_LONG | エンコードするペイロードが4296文字を超えている（QRの理論上の最大値） |
INVALID_JSON | ボディをJSONとして解析できない |
INVALID_HEX | 色の文字列が #RGB、#RRGGBB、#RRGGBBAA のいずれでもない |
INVALID_FIELD_VALUE | 汎用 — どのフィールドかは field で示されます |
VALUE_OUT_OF_RANGE | 数値フィールドが記載の範囲外 |
LOW_CONTRAST | 前景と背景のコントラストが4:1未満で、エンジンが自動修正できない |
LOGO_TOO_LARGE | ECCがH未満で logoSizePercent が25を超えている |
FILE_TOO_LARGE | マルチパートのアップロードが10 MBを超えている |
MULTIPART_CONFIG_MISSING | form-dataリクエストに config フィールドがない |
| コード | 意味 |
|---|
UNAUTHORIZED | X-RapidAPI-Proxy-Secret がない、または誤っている |
INVALID_INTERNAL_SIGNATURE | BFFのHMACの検証に失敗した |
INTERNAL_TS_EXPIRED | BFFのタイムスタンプが±60秒の範囲外 |
LLM_API_KEY_INVALID | プロバイダーのキーが無効（マーケットプレイスのAIエンドポイントのみ） |
ゲートウェイ https://qr-branding.com/api/v1/*（ユーザーAPIキー）は、同じ success / error / code のエンベロープで、小文字の独自コードを追加で返します。
| ステータス | コード | 意味 |
|---|
400 | invalid_body | 本文を解析できませんでした |
401 | missing_api_key | X-API-Key ヘッダーがありません |
401 | invalid_api_key | キーが認識できない、失効している、または形式が不正です |
402 | studio_required | キーは有効ですが、アカウントに有効な Studio パックがありません。docs と pricing のリンクを含みます |
402 | out_of_api_credits | Studio クレジットが残っていない状態で当社キーによる AI 生成を行いました。docs と pricing のリンクを含みます |
413 | payload_too_large | 本文が 1 MiB を超えています |
413 | output_too_large | 生成されたファイルが 10 MB を超えています。PNG を指定するか、outputWidth を小さくしてください |
415 | multipart_not_supported | ゲートウェイは JSON のみ受け付けます |
POST /api/checkout（/pricing の購入ボタン）は、同意がない場合に { "error": "withdrawal_waiver_required" } を返します。
| ステータス | コード | 意味 |
|---|
400 | withdrawal_waiver_required | 支払い前のチェックボックス（同意と撤回権の放棄）にチェックが入っていません。料金とクレジットを参照してください |
| コード | 意味 |
|---|
AI_GENERATION_FAILED | LLMが使える設定を返さなかった — より明確なプロンプトを試してください |
AI_REQUEST_TIMEOUT | フォールバックチェーンのどのプロバイダーも合計 45 秒の期限内に応答しなかった（各プロバイダーは最大 20 秒）。503 を返します。少し待って再試行してください |
AI_QUOTA_EXCEEDED | フォールバックチェーンのすべてのプロバイダーがクォータまたは利用上限で拒否した。503 を返します。すぐに再試行しても解決しないため、時間をおいて再試行してください |
AI_CONFIG_INVALID | LLMが返した設定をエンジンが拒否した（まれ。クリエイティビティを下げて再試行） |
INVALID_LLM_PROVIDER | マーケットプレイスのみ — llmProvider が openai anthropic google mistral cohere groq xai deepseek qwen local に含まれない |
INVALID_LLM_MODEL | マーケットプレイスのみ — llmModel がモデル ID の形式ではない |
| コード | 意味 |
|---|
OUTPUT_TOO_COMPLEX | このデザインでは 20 MB を超える SVG / PDF、または 1 辺 5120 px を超える内部ラスターキャンバスが必要になります。SVG のサイズはモジュール数に比例して増えます。短い URL のテンプレートは約 1.5 MB、300 文字の URL では約 17 MB です。PNG で書き出すか、内容を短くするか、よりシンプルなモジュール形状を使ってください |
| コード | 意味 |
|---|
INTERNAL_ERROR | 予期しないエラー — リクエストIDを添えて報告してください |
QR_GENERATION_FAILED | レンダリングエンジン自体が例外を投げた。判明している場合は問題のフィールドを含みます |
SERVER_BUSY | 高解像度の同時レンダリングが多すぎる。しばらく待って再試行してください |
| フィールド | 制約 |
|---|
content | 1〜4296文字 |
prompt（AI） | 1〜10000文字 |
creativity（AI） | 0.0–1.0 |
pixelsPerModule | 1–100 |
outputWidth / outputHeight | 64–4096 |
logoSizePercent | 3–40（ECC Hでは、エンジンが 25 でソフト上限を適用） |
moduleScale | 0.5–1.0 |
moduleSizeVariation | 0.0–0.15（ソフト上限。これを超えると読み取れなくなります） |
qrShapeRadius | 0–50 |
| ロゴ / 背景のファイルサイズ | 10 MB以下 |
| ロゴ / 背景の画像形式 | PNG、JPG、GIF、BMP、WebP |
| SVG / PDF ドキュメント | ≤ 20 MB (OUTPUT_TOO_COMPLEX) |
| ユーザーキーのゲートウェイ経由のファイル | ≤ 10 MB (output_too_large) |