Errores

Todas las respuestas de error comparten este formato:

{
  "success": false,
  "code": 402,
  "type": "INSUFFICIENT_TOKENS",
  "message": "No tienes tokens suficientes. Recarga para seguir creando.",
  "requestId": "45006073-0542-4dc0-91df-3bc79cadc1da"
}

Campo	Tipo	Descripción
`success`	`boolean`	Siempre `false`.
`code`	`number`	Código de estado HTTP.
`type`	`string`	Identificador estable del error. Úsalo en tu código para decidir qué hacer.
`message`	`string`	Texto legible. Puede ser genérico (por ejemplo `Unauthorized`) y cambiar sin aviso: no lo uses para lógica.
`requestId`	`string`	ID de la petición. Inclúyelo al contactar con soporte.
`errors`	`array`	Solo en errores `422 VALIDATION_ERROR`: detalle de cada parámetro inválido.

Los errores 5xx siempre devuelven el mensaje genérico Error interno del servidor.

Errores de validación

{
  "success": false,
  "code": 422,
  "type": "VALIDATION_ERROR",
  "message": "Parameters validation error!",
  "errors": [
    { "type": "required", "field": "prompt", "message": "The 'prompt' field is required." }
  ]
}

Tipos de error

Autenticación y permisos

Código	Tipo	Causa
`401`	`ERR_NO_TOKEN`	Falta la cabecera `Authorization` o no empieza por `Bearer pk_live_`.
`401`	`API_KEY_INVALID`	Key inexistente, desactivada o caducada.
`401`	`API_KEY_ERROR`	No se pudo validar la key. Reintenta.
`403`	`INSUFFICIENT_SCOPE`	La key no tiene el scope necesario.
`403`	`TEAM_MISMATCH`	El `:teamId` de la ruta no es el equipo de la key.
`403`	`MODEL_BLOCKED`	El modelo no está disponible para tu equipo.
`402`	`PLAN_FEATURE_REQUIRED`	Tu plan no incluye esta funcionalidad.

Tokens y límites

Código	Tipo	Causa
`402`	`INSUFFICIENT_TOKENS`	Saldo insuficiente.
`429`	`API_KEY_RATE_LIMIT`	Superado el rate limit de la key.
`429`	`CONCURRENT_JOBS_LIMIT`	Demasiados jobs en curso para tu plan.
`429`	`WORKFLOW_PARALLEL_LIMIT`	Demasiadas ejecuciones simultáneas del mismo workflow.
`503`	`GENERATION_BUSY`	Capacidad de generación saturada. Reintenta con backoff.

Peticiones

Código	Tipo	Causa
`400`	`BAD_REQUEST`	Petición inválida.
`400`	`PRICING_ERROR`	No se pudo calcular el precio.
`400`	`MISSING_INPUTS`	Faltan entradas obligatorias del workflow.
`400`	`WORKFLOW_INACTIVE`	El workflow está desactivado.
`400`	`ALREADY_FINISHED`	La ejecución ya ha terminado.
`404`	`NOT_FOUND`	Recurso o endpoint inexistente.
`409`	`CONFLICT`	El job ya no está en cola y no puede cancelarse.
`413`	`REFERENCE_IMAGES_TOO_LARGE`	Las imágenes de referencia superan 8 MB en total.
`422`	`VALIDATION_ERROR`	Parámetros inválidos (ver `errors`).
`422`	`INVALID_SIZE`	`target_width`/`target_height` fuera de rango.
`422`	`CONTENT_BLOCKED`	El proveedor bloqueó el contenido. No reintentes con el mismo prompt.
`500`	`INTERNAL_ERROR`	Error interno.

Reintentos

Reintenta 429, 503 y 5xx con backoff exponencial (1 s, 2 s, 4 s…).
No reintentes 4xx sin cambiar la petición.
Los endpoints que consumen tokens no son idempotentes: si una petición se corta por timeout, comprueba el resultado antes de repetirla. Para operaciones largas usa jobs.