Errores de la API: qué significa cada código y cómo solucionarlo

FastOG devuelve códigos de error legibles por máquina cuando falla una petición: el render de una imagen OG firmada o una llamada a una de las superficies de administración del producto. Toda respuesta de error incluye:

• error — el token corto heredado. Sigue presente en todos los fallos para que un cliente antiguo siga funcionando.
• code — el mismo código de error estable y documentado (tabla a continuación), con el nombre que usa la API pública.
• message — una descripción de una frase sobre qué ha fallado.
• hint — una descripción breve en lenguaje llano de qué ha fallado y cómo solucionarlo.
• docs_url — un enlace a esta página, anclado en la sección de ese código.
• request_id — correlaciona este fallo HTTP con una fila de la tabla Render Logs del dashboard (también se devuelve en la cabecera de respuesta X-Request-ID). Una superficie sin nada que correlacionar responde null, pero la clave siempre está presente.

Las superficies del producto —el admin de Shopify, el WooCommerce Studio, el puente de Wix y la demo— responden con el mismo envelope para los códigos de abajo, así que un fallo significa lo mismo allí donde te lo encuentres. Una superficie de módulo puede mantener el estado HTTP que siempre ha devuelto para un código (por ejemplo, render_failed responde 503 en la exportación de portada y 502 en la API pública); el código, el mensaje, la pista y el enlace a la documentación no cambian.

Leer una respuesta de error

{
  "error": "invalid_signature",
  "code": "invalid_signature",
  "message": "The signature does not match.",
  "hint": "The signature did not match. Re-sign with your HMAC secret after every param change.",
  "request_id": "5f2a9c1e-..."
}

Si recibes una respuesta que no entiendes, el camino más rápido es:

1. Anota el code.
2. Revisa tu constructor de URL — la mayoría de los fallos son errores de firma, no problemas de cuenta.
3. Consulta el código de abajo para conocer la causa exacta y la solución.
4. En el dashboard, abre Render Logs y filtra por el mismo error_code — cada fila muestra los parámetros solicitados para que puedas reproducirlo (y confirmar que request_id coincide).

Firma y autenticación

missing_signature

A tu solicitud le faltan los parámetros de consulta key y/o s (firma).

Solución: asegúrate de que tu URL incluya tanto key=<api-key> como s=<hmac-signature>. Usa el SDK o el recorrido de /docs/hmac-signature-guide para construirla.

invalid_signature

El valor de s no coincidía con lo que produce tu secreto HMAC para esta URL.

Solución: la firma cubre todos los parámetros de consulta excepto s, con las claves ordenadas. Cambiar cualquier parámetro —incluido reordenarlos, diferencias de codificación de URL o añadir espacios en blanco— invalida la firma. Vuelve a firmar después de cada cambio. Confirma que tu secreto es el mismo que se mostró al crear la clave de API.

invalid_signature_format

El valor de s no es una cadena hexadecimal de 64 caracteres.

Solución: la firma debe ser el SHA-256 en hexadecimal sin procesar (minúsculas a-f0-9). Si estás codificando en base64 o truncando la salida, usa hexadecimal simple.

expired_timestamp

La marca de tiempo t que proporcionaste tiene más de 5 minutos de antigüedad.

Solución: vuelve a generar la marca de tiempo cada vez que construyas una URL. Este código se aplica al flujo heredado de URL firmada; el flujo actual de HMAC v2 no tiene marca de tiempo.

invalid_api_key

El key que pasaste no existe.

Solución: copia la clave de API completa desde el panel —es el identificador público que empieza por sk_. Es pública y segura en las URL; el secreto (nunca en las URL) es lo que demuestra la posesión.

missing_hmac_secret

La clave de API no tiene configurado ningún secreto HMAC.

Solución: crea una nueva clave de API en el panel —el secreto HMAC se genera y se muestra una sola vez al crearla.

Parámetro / entrada

invalid_image_url

Una prop que contiene una URL (image, brand_logo, logo, avatar, background_image, ...) no es una URL http(s) pública.

Solución: pasa una URL https://... accesible públicamente. Se rechazan localhost, las IP privadas y las rutas sin dominio para evitar la falsificación de peticiones del lado del servidor.

Suscripción

subscription_required (402)

La solicitud llegó a la Dynamic API, pero tu cuenta no tiene un plan activo. El acceso a la API es solo por suscripción: el plan es la condición indispensable y ofrece la misma cobertura y la misma escala de capacidades que venden las aplicaciones de FastOG. Las renderizaciones en sí no se miden: no hay cuota mensual de renderizaciones ni facturación por exceso.

Solución: elige un plan de Dynamic API en el panel y crea una clave de API. La respuesta incluye un top_up_url que apunta a la página de planes.

Servicio de renderizado

store_blocked (403)

FastOG ha pausado el renderizado de la tienda asociada a esta clave (por ejemplo, por abuso o un uso descontrolado). Las imágenes ya almacenadas en caché en el edge pueden seguir sirviéndose hasta que caduquen. Contacta con soporte para resolverlo; nada de lo que cambies en la petición solucionará esto.

render_unreachable

No se pudo contactar con el servicio de renderizado (ventana breve de reinicio).

Solución: vuelve a intentarlo en unos segundos. El renderizado no se contabilizó en este intento.

render_failed

El servicio de renderizado devolvió un error para tu petición.

Solución: verifica las props de tu plantilla — valores largos o mal formados, campos no admitidos o una imagen de origen inaccesible. La respuesta incluye el status subyacente. El renderizado no se contabilizó.

Superficies de administración de la tienda

Estos códigos responden desde el administrador de Shopify y el WooCommerce Studio — los editores integrados en los que trabaja un comerciante en lugar de la API firmada. Varios se comparten con la API pública (invalid_image_url, render_failed, invalid_signature); esos mantienen la entrada documentada arriba.

Puente de Wix

El puente de Wix lo firma la app de Wix, no una sesión de comerciante, así que sus fallos van dirigidos al desarrollador de la app. Todas las respuestas siguen incluyendo code y request_id; el id de la petición del puente es el del sobre firmado.

Superficie de la demo

La demo es la consola de ventas exclusiva para el propietario, no un endpoint para comercios.

Códigos del editor de reglas con ámbito

Los editores de reglas con ámbito (el admin de Shopify y WooCommerce Studio) traducen estos tokens por sí mismos, al idioma del propio comerciante, por lo que sus respuestas incluyen error y code pero no hint — una segunda descripción en inglés solo se desviaría de la localizada que el comerciante ve realmente:

scope_already_defined, scoped_rule_limit_reached, scoped_rules_not_on_plan, scope_value_required, scope_value_too_long, unknown_scope_type, base_rule_required, scoped_rules_product_only, cannot_delete_base_rule.

¿Sigues atascado?

• Abre la página Render Logs del panel: cada resultado (éxito + rechazo) aparece listado con su error_code, el estado HTTP y los parámetros solicitados.
• Ejecuta php artisan og:diagnose sobre una URL firmada para recorrer todo el pipeline y ver en qué etapa falla.
• Consulta en la barra lateral la documentación del framework que estés usando (Next.js, Express, SvelteKit, ...).