Referencia de errores

Todas las respuestas de error tienen la misma forma: código de estado + code legible por máquina + mensaje para personas + field opcional que señala la entrada problemática.

Formato

{
  "success": false,
  "error": "Content length (5000) exceeds maximum allowed (4296 characters).",
  "code": "CONTENT_TOO_LONG",
  "field": "content"
}

Códigos de estado HTTP

Estado	Significado
`200`	Correcto
`400`	Error de validación: corrige la entrada y vuelve a intentarlo
`401`	Falta la cabecera de autenticación o es incorrecta
`402`	Pasarela de claves de usuario: falta el plan Studio o se han agotado los créditos de API
`404`	Endpoint no encontrado
`413`	Cuerpo demasiado grande (>10 MB) o, en la pasarela de claves de usuario, un archivo generado de más de 10 MB (`output_too_large`)
`422`	El motor no ha podido producir un QR escaneable ni siquiera tras la corrección automática (`QR_UNSCANNABLE`), o la salida superaría el presupuesto (`OUTPUT_TOO_COMPLEX`)
`429`	Límite de peticiones: consulta `Retry-After`
`500`	Error interno: regístralo y vuelve a intentarlo
`503`	Servidor ocupado (muchos renderizados grandes simultáneos) o proveedores de IA sin capacidad (`AI_QUOTA_EXCEEDED`)

Errores de validación (400)

Código	Significado
`MISSING_REQUIRED_FIELD`	`content` (o `prompt` en los endpoints de IA) está vacío
`CONTENT_TOO_LONG`	Contenido codificado > 4296 caracteres (máximo teórico de un QR)
`INVALID_JSON`	El cuerpo no se puede interpretar como JSON
`INVALID_HEX`	Un color no es `#RGB`, `#RRGGBB` ni `#RRGGBBAA`
`INVALID_FIELD_VALUE`	Genérico: `field` te dirá cuál
`VALUE_OUT_OF_RANGE`	Campo numérico fuera de los límites documentados
`LOW_CONTRAST`	Primer plano frente a fondo < 4:1; el motor no puede corregirlo solo
`LOGO_TOO_LARGE`	`logoSizePercent` > 25 con ECC < H
`FILE_TOO_LARGE`	Subida multipart > 10 MB
`MULTIPART_CONFIG_MISSING`	Falta el campo `config` en una petición form-data

Errores de autenticación (401)

Código	Significado
`UNAUTHORIZED`	Falta `X-RapidAPI-Proxy-Secret` o es incorrecto
`INVALID_INTERNAL_SIGNATURE`	El HMAC del BFF no ha superado la verificación
`INTERNAL_TS_EXPIRED`	La marca de tiempo del BFF está fuera de la ventana de ±60 s
`LLM_API_KEY_INVALID`	Tu clave del proveedor (solo en el endpoint de IA de Marketplace)

Errores de la pasarela de claves de usuario

La pasarela https://qr-branding.com/api/v1/* (Claves de API de usuario) añade sus propios códigos, en minúsculas, con el mismo formato success / error / code:

Estado	Código	Significado
`400`	`invalid_body`	No se ha podido interpretar el cuerpo
`401`	`missing_api_key`	Falta la cabecera `X-API-Key`
`401`	`invalid_api_key`	Clave no reconocida, revocada o mal formada
`402`	`studio_required`	La clave es válida, pero la cuenta no tiene un pack Studio activo. Incluye los enlaces `docs` y `pricing`
`402`	`out_of_api_credits`	Generación con IA en nuestras claves sin créditos de Studio. Incluye los enlaces `docs` y `pricing`
`413`	`payload_too_large`	Cuerpo de más de 1 MiB
`413`	`output_too_large`	El archivo generado pesa más de 10 MB. Pide PNG o un `outputWidth` menor
`415`	`multipart_not_supported`	La pasarela solo acepta JSON

Errores del pago

POST /api/checkout (el botón de compra de /pricing) responde con { "error": "withdrawal_waiver_required" } cuando falta el consentimiento:

Estado	Código	Significado
`400`	`withdrawal_waiver_required`	No se ha marcado la casilla previa al pago (consentimiento y renuncia al derecho de desistimiento). Consulta Precios y créditos

Errores de generación con IA

Código	Significado
`AI_GENERATION_FAILED`	El LLM no ha devuelto ninguna configuración utilizable; prueba con un prompt más claro
`AI_REQUEST_TIMEOUT`	Ningún proveedor de la cadena de respaldo ha respondido dentro del plazo total de 45 s (cada uno tiene como máximo 20 s). Responde 503; reintenta en un momento
`AI_QUOTA_EXCEEDED`	Todos los proveedores de la cadena de respaldo han rechazado la petición por cuota o tope de gasto. Responde 503; reintentar enseguida no sirve, vuelve a intentarlo más tarde
`AI_CONFIG_INVALID`	El LLM ha devuelto una configuración que el motor ha rechazado (poco habitual; reintenta con menos creatividad)
`INVALID_LLM_PROVIDER`	Solo Marketplace: `llmProvider` no está en `openai anthropic google mistral cohere groq xai deepseek qwen local`
`INVALID_LLM_MODEL`	Solo Marketplace: `llmModel` no tiene formato de ID de modelo

Errores de presupuesto de salida (422)

Código	Significado
`OUTPUT_TOO_COMPLEX`	El diseño produciría un SVG o un PDF de más de 20 MB, o un lienzo raster interno de más de 5120 px por lado. El tamaño de un SVG crece con el número de módulos: una plantilla con una URL corta ocupa ~1,5 MB y con una URL de 300 caracteres ~17 MB. Expórtalo en PNG, acorta el contenido o usa formas de módulo más sencillas

Errores del servidor (500/503)

Código	Significado
`INTERNAL_ERROR`	Inesperado: avísanos indicando el id de la petición
`QR_GENERATION_FAILED`	Ha fallado el propio motor de renderizado. Incluye el campo problemático cuando se conoce
`SERVER_BUSY`	Demasiados renderizados de alta resolución simultáneos. Espera y vuelve a intentarlo

Restricciones de validación de campos

Campo	Restricción
`content`	1–4296 caracteres
`prompt` (IA)	1–10000 caracteres
`creativity` (IA)	`0.0–1.0`
`pixelsPerModule`	`1–100`
`outputWidth` / `outputHeight`	`64–4096`
`logoSizePercent`	`3–40` (el motor aplica un tope blando de `25` con ECC H)
`moduleScale`	`0.5–1.0`
`moduleSizeVariation`	`0.0–0.15` (tope blando; cualquier valor mayor impide el escaneo)
`qrShapeRadius`	`0–50`
Tamaño del archivo de logo / fondo	≤ 10 MB
Tipos de imagen de logo / fondo	PNG, JPG, GIF, BMP, WebP
Documento SVG / PDF	≤ 20 MB (`OUTPUT_TOO_COMPLEX`)
Archivo a través de la pasarela de claves de usuario	≤ 10 MB (`output_too_large`)