Errores técnicos de la API de Tryon (Códigos 4xx)

Este artículo documenta los códigos de error internos/técnicos que la API de Tryon puede devolver. Estos errores son diferentes de los errores visibles para el usuario 1001–1008: indican problemas a nivel de integración o infraestructura y son más útiles para desarrolladores y administradores de tienda diagnosticando una integración.

Los clientes finales normalmente no ven estos mensajes — el widget los captura y muestra un genérico "Algo salió mal". Para diagnosticar, inspecciona la pestaña de red del navegador y revisa el cuerpo de la respuesta de la API para encontrar el campo code.

Referencia completa

HTTP	Código	Qué significa	Cómo resolver
401	missing_license_key	La solicitud de la API no incluyó una license key en los headers.	Verifica que la integración del widget incluya la license key en cada solicitud. Si usas el widget oficial de Tryon, confirma que el PIN de tu tienda esté correctamente configurado en el snippet de embed.
404	license_not_found	La license key proporcionada no corresponde a ninguna tienda activa.	Confirma que el PIN/license key en tu código de embed coincide con el mostrado en tu panel. Si la tienda fue eliminada recientemente o la suscripción cancelada, la clave deja de funcionar.
400	missing_customer_uuid	La solicitud no incluyó un UUID de cliente identificando al visitante.	Asegúrate de que tu integración del widget genere y envíe un UUID único de cliente para cada sesión. El widget oficial lo hace automáticamente.
400	missing_customer_type	El tipo de cliente (guest, registered, buyer) no se proporcionó en la solicitud.	Verifica la configuración del widget. El tipo de cliente debe ser uno de: guest, registered o buyer. Contacta a soporte si no puedes determinar el valor correcto.
400	invalid_customer_type	El tipo de cliente enviado en la solicitud no es uno de los valores aceptados.	Los valores aceptados son exactamente: guest, registered o buyer. Cualquier otra cadena (o diferencia de mayúsculas) será rechazada.
400	missing_recaptcha_token	El token de reCAPTCHA es obligatorio pero no se incluyó en la solicitud.	Si tu widget tiene reCAPTCHA habilitado, confirma que el recaptcha_site_key esté configurado y que el token se esté generando en el cliente antes de la solicitud.
400	missing_required_parameters	Falta uno o más parámetros obligatorios en el cuerpo de la solicitud.	Inspecciona la solicitud de red para identificar qué campo falta. Sospechas comunes: product_id, customer_uuid, customer_type o los datos de la foto. Contacta a soporte con el payload de la solicitud si no puedes identificar el problema.
400	invalid_json	El cuerpo de la solicitud no se pudo interpretar como JSON válido.	Suele ser un bug en integraciones personalizadas que construyen la solicitud manualmente. Valida el payload JSON con un linter, o utiliza el widget oficial que maneja la serialización automáticamente.
400	invalid_feedback	El payload de feedback enviado contiene valores inválidos (ej.: rating fuera de rango).	Los ratings de feedback deben ser valores válidos (típicamente 1 o -1 / positivo o negativo). Revisa el código de integración que construye la solicitud de feedback.
404	settings_not_found	La configuración de la tienda no pudo ser cargada.	Abre tu panel y verifica que la tienda exista y tu suscripción esté activa. Si el problema persiste, contacta a soporte — puede indicar un problema de datos en el backend.
404	product_not_found	El product_id enviado en la solicitud no existe en esta tienda.	Verifica que el producto exista en Dashboard → Products y esté con estado ACTIVE. Si importaste productos desde una plataforma de e-commerce, confirma que la importación se completó correctamente.
404	job_not_found	El ID del job de generación referenciado en la solicitud no existe o ha expirado.	Los jobs son de corta duración. Si estás consultando el resultado de un job, asegúrate de iniciar una nueva generación en lugar de reutilizar un ID antiguo. A menudo esto significa una pestaña obsoleta — recargar el widget debería resolverlo.
404	image_not_found	La imagen solicitada (ej.: una foto generada anteriormente) no se encontró en el almacenamiento.	Si la imagen fue generada hace mucho tiempo, puede haber sido eliminada del storage según tu política de retención. Genera una nueva foto para reemplazarla.
409	feedback_already_submitted	El cliente ya envió feedback para esta foto generada.	Cada foto acepta solo un rating de feedback por cliente. Si el cliente quiere cambiar su rating, esto no es compatible actualmente — solo se registra el primer envío.
403	cors_origin_not_allowed	La solicitud se originó desde un dominio que no está en la lista de orígenes permitidos de la tienda.	En Dashboard → E-commerce, agrega el dominio donde el widget está embebido a la lista de orígenes permitidos. Subdominios y protocolo deben coincidir exactamente (https://shop.example.com es diferente de https://www.shop.example.com).
429	rate_limited	Se enviaron demasiadas solicitudes en un período corto desde este cliente/IP.	Espera unos segundos e inténtalo de nuevo. Si estás integrando programáticamente, agrega backoff exponencial entre reintentos. Rate limiting persistente desde tráfico real puede indicar abuso — contacta a soporte.
500	internal_server_error	Ocurrió un error inesperado en la infraestructura del backend de Tryon.	Rara vez es causado por tu integración. Reintenta la solicitud después de unos segundos. Si el error persiste, contacta a [email protected] con el PIN de tu tienda y la hora aproximada del error.

Cómo encontrar el código de error en una solicitud real

1. Abre las Herramientas de Desarrollador del navegador (F12 o Ctrl+Shift+I / Cmd+Opt+I).
2. Ve a la pestaña Network y reproduce la acción que disparó el error.
3. Haz clic en la solicitud fallida (estado rojo) y abre la pestaña Response.
4. Busca el campo JSON llamado code — ese es el valor correspondiente en la tabla anterior.