Every error response is the same shape. Status code + machine-readable code + human message + optional field pointing at the offending input.
{
"success": false,
"error": "Content length (5000) exceeds maximum allowed (4296 characters).",
"code": "CONTENT_TOO_LONG",
"field": "content"
}
| Status | Meaning |
|---|
200 | Success |
400 | Validation error — fix the input and retry |
401 | Auth header missing or wrong |
402 | User-key gateway: Studio plan missing or API credits used up |
404 | Endpoint not found |
413 | Body too large (>10 MB) or, through the user-key gateway, a rendered file over 10 MB (output_too_large) |
422 | Engine couldn't produce a scannable QR even after auto-fix (QR_UNSCANNABLE), or the output would exceed the budget (OUTPUT_TOO_COMPLEX) |
429 | Rate limit — see Retry-After |
500 | Internal — log + retry |
503 | Server busy (large concurrent renders) or AI providers out of capacity (AI_QUOTA_EXCEEDED) |
| Code | Meaning |
|---|
MISSING_REQUIRED_FIELD | content (or prompt on AI endpoints) is empty |
CONTENT_TOO_LONG | Encoded payload > 4296 chars (QR theoretical max) |
INVALID_JSON | Body doesn't parse as JSON |
INVALID_HEX | A color string isn't #RGB, #RRGGBB or #RRGGBBAA |
INVALID_FIELD_VALUE | Generic — field will tell you which |
VALUE_OUT_OF_RANGE | Numeric field outside the documented bounds |
LOW_CONTRAST | foreground vs background < 4:1; engine can't auto-fix |
LOGO_TOO_LARGE | logoSizePercent > 25 with ECC < H |
FILE_TOO_LARGE | Multipart upload > 10 MB |
MULTIPART_CONFIG_MISSING | config field absent in form-data request |
| Code | Meaning |
|---|
UNAUTHORIZED | X-RapidAPI-Proxy-Secret missing or wrong |
INVALID_INTERNAL_SIGNATURE | BFF HMAC failed verification |
INTERNAL_TS_EXPIRED | BFF timestamp outside ±60s window |
LLM_API_KEY_INVALID | Your provider key (only on marketplace AI endpoint) |
The gateway at https://qr-branding.com/api/v1/* (User API keys) adds its own lowercase codes, with the same success / error / code envelope:
| Status | Code | Meaning |
|---|
400 | invalid_body | The body couldn't be parsed |
401 | missing_api_key | No X-API-Key header |
401 | invalid_api_key | Key not recognised, revoked or malformed |
402 | studio_required | Valid key, but the account has no active Studio pack. Includes docs and pricing links |
402 | out_of_api_credits | AI generation on our keys with no Studio credits left. Includes docs and pricing links |
413 | payload_too_large | Body over 1 MiB |
413 | output_too_large | The rendered file is larger than 10 MB. Request PNG or a smaller outputWidth |
415 | multipart_not_supported | The gateway only accepts JSON |
POST /api/checkout (the buy button on /pricing) answers { "error": "withdrawal_waiver_required" } when the consent is missing:
| Status | Code | Meaning |
|---|
400 | withdrawal_waiver_required | The pre-checkout box (consent and waiver of the right of withdrawal) wasn't ticked. See Pricing & credits |
| Code | Meaning |
|---|
AI_GENERATION_FAILED | LLM returned no usable config — try a clearer prompt |
AI_REQUEST_TIMEOUT | No provider in the fallback chain answered within the 45 s total (each gets at most 20 s). Answers 503; retry in a moment |
AI_QUOTA_EXCEEDED | Every provider in the fallback chain refused for quota or spend cap. Answers 503; retrying right away will not help, try again later |
AI_CONFIG_INVALID | LLM returned a config the engine rejected (rare, retry with lower creativity) |
INVALID_LLM_PROVIDER | Marketplace only — llmProvider not in openai anthropic google mistral cohere groq xai deepseek qwen local |
INVALID_LLM_MODEL | Marketplace only — llmModel is not a well-formed model ID |
| Code | Meaning |
|---|
OUTPUT_TOO_COMPLEX | The design would produce an SVG or PDF over 20 MB, or an internal raster canvas over 5120 px per side. SVG size grows with the number of modules: a template with a short URL is ~1.5 MB, with a 300-character URL ~17 MB. Export as PNG, shorten the content or use simpler module shapes |
| Code | Meaning |
|---|
INTERNAL_ERROR | Unexpected — please report with the request id |
QR_GENERATION_FAILED | The rendering engine itself threw. Includes the offending field when known |
SERVER_BUSY | Too many concurrent high-resolution renders. Wait and retry |
| Field | Constraint |
|---|
content | 1–4296 chars |
prompt (AI) | 1–10000 chars |
creativity (AI) | 0.0–1.0 |
pixelsPerModule | 1–100 |
outputWidth / outputHeight | 64–4096 |
logoSizePercent | 3–40 (engine soft-caps at 25 with ECC H) |
moduleScale | 0.5–1.0 |
moduleSizeVariation | 0.0–0.15 (soft cap, anything higher breaks scanning) |
qrShapeRadius | 0–50 |
| Logo / background file size | ≤ 10 MB |
| Logo / background image types | PNG, JPG, GIF, BMP, WebP |
| SVG / PDF document | ≤ 20 MB (OUTPUT_TOO_COMPLEX) |
| File through the user-key gateway | ≤ 10 MB (output_too_large) |