Envoltorio de errores
{
"error": {
"code": "asset_not_found",
"message": "No asset with id 42 for this shop",
"status": 404,
"request_id": "req_..."
}
}Incluye el request id al ponerte en contacto con el soporte.
Códigos de error habituales
| HTTP | Código | Significado |
|---|---|---|
| 400 | invalid_request | JSON mal formado o campo ausente. |
| 400 | idempotency_key_required | Solicitud de escritura sin Idempotency-Key. |
| 401 | unauthorized | Token ausente, no válido, desconocido o revocado. |
| 402 | plan_required | La tienda está en el plan Free. La API externa requiere un plan de pago. En una notificación de actualización de producto también significa que la suscripción de la tienda no está activa, y una campaña detenida por cualquiera de los dos motivos después de ponerse en cola informa error: plan_required en GET /notifications/{id}. |
| 403 | forbidden | La API externa está desactivada (el interruptor global de emergencia), a la clave de API le falta un alcance que la solicitud necesita o, en las rutas de notificaciones de actualización de producto, Alva ha desactivado esas notificaciones como freno de emergencia. Contacta con nosotros si una clave con los alcances correctos la recibe. |
| 403 | notifications_suspended | Las notificaciones de actualización de producto están suspendidas para esta tienda tras quejas de spam en campañas anteriores. Ningún reintento sirve — contacta con soporte. |
| 404 | asset_not_found, mapping_not_found, order_not_found, category_not_found, job_not_found | El recurso no existe o pertenece a otra tienda. |
| 404 | notification_not_found | La notificación de actualización de producto no existe o pertenece a otra tienda. |
| 409 | idempotency_conflict | La misma clave se reutilizó con una solicitud distinta. |
| 409 | stamping_in_progress | El reenvío está bloqueado mientras el marcado del PDF está pendiente. |
| 409 | delivery_not_yet_released | El producto tiene configurado un retraso de entrega de descargas y los archivos del comprador aún no se han desbloqueado. error.details.release_at es el instante ISO 8601 en que se desbloquean; el comerciante puede liberar el pedido antes con el endpoint grant-downloads. |
| 409 | notification_not_cancellable | Solo se puede cancelar una notificación de actualización de producto en cola. Esta ya ha empezado a enviarse, ha terminado, ha fallado o se canceló — error.details.status indica cuál. |
| 409 | app_not_installed | Alva no tiene una sesión de Shopify activa para la tienda, normalmente porque se desinstaló la app, así que no se puede ejecutar una solicitud que necesita Shopify — una escritura de asignación o una notificación de actualización de producto cuya nota nombra un metacampo o que envía variant_ids. Abre o reinstala la app en el panel de administración de Shopify y reintenta. |
| 409 | multiple_mappings_match | Un id de Shopify coincide con más de una asignación, así que Alva no puede saber a cuál te refieres. En POST /products/{id}/notifications, error.details.ambiguous_variant_ids lista las variantes solicitadas que sirve más de una asignación. |
| 409 | personalized_product | El producto es personalizado. La personalización se define para todo el producto, así que POST /mappings con shopify_variant_ids no puede añadirle una asignación específica de variante (no se escribe nada), y POST /products/{id}/notifications no puede notificar a sus compradores, porque cada pedido tiene su propio archivo. |
| 422 | storage_quota_exceeded | La subida o importación superaría la cuota de almacenamiento. |
| 422 | key_limit_reached | La tienda ya tiene el máximo de 25 claves de API activas; revoca una primero. |
| 422 | withdrawal_consent_required | La tienda tiene activado el consentimiento del derecho de desistimiento de la UE y el pedido aún no tiene registro de consentimiento; las URLs de descarga se emiten una vez que el cliente da su consentimiento. |
| 422 | email_disabled | Los emails a clientes están desactivados en la configuración de email de la app. Lo devuelven el reenvío del email de un pedido, POST /orders/{id}/assignments con send_email: true (no se crea nada), POST /products/{id}/notifications y, como resultado de notify_customers, una escritura de asignación (la asignación en sí se guarda igualmente). Actívalos y reintenta. |
| 422 | invalid_message | La nota de actualización de producto incumplió una regla: en blanco, demasiado larga (también una vez rellenadas sus variables), una variable desconocida o sin cerrar, más de cinco metacampos distintos, un enlace o una dirección de email (también dentro del valor de un metacampo), o un metacampo que no existe, es demasiado largo o es de un tipo que no se puede mostrar en un email. error.details.errors[] nombra cada regla; error.details.max_length es el máximo (2.000). No se envió ni se escribió nada. En una escritura de asignación con notify_customers, solo las reglas sobre el propio texto de la nota rechazan la escritura; un problema con un metacampo se informa en data.notification después de guardar la asignación. |
| 422 | no_downloadable_content | Ninguna asignación objetivo tiene archivos, packs o enlaces que anunciar; las asignaciones solo con clave y las personalizadas no pueden ser objeto de una actualización de producto. Con variant_ids, cuando el producto tiene otra asignación que se podría notificar, error.details.mapping_ids indica las asignaciones a las que se resolvieron esas variantes. |
| 422 | no_eligible_recipients | No hay a quién enviar: ningún comprador de las asignaciones objetivo acepta recibir emails. error.details.opted_out_count indica cuántos se han dado de baja. Una asignación recién creada aún no tiene compradores. |
| 429 | rate_limited | Se alcanzó el límite de claves de API o de reenvíos del pedido. |
| 429 | notification_cooldown | Una notificación de actualización de producto por producto cada 7 días, contando todas sus variantes y todos los orígenes — o una campaña del producto sigue en cola o enviándose. No es el bucket de tokens: Retry-After puede llegar a siete días y error.details.next_available_at es el instante en que el producto queda libre de nuevo. No lo reintentes automáticamente — programa la siguiente llamada en next_available_at. Cancelar una campaña no restablece el límite; usa dry_run para comprobar una nota antes de enviar. |
| 429 | too_many_active_notifications | La tienda ya tiene 5 notificaciones de actualización de producto en cola o enviándose, contando todos los productos y todos los orígenes. error.details.limit es el máximo y error.details.active_notification_ids lista esas campañas, de la más antigua a la más reciente. No hay Retry-After: consulta periódicamente GET /notifications/{id} de una de ellas y reintenta cuando haya terminado. Un dry run se rechaza de la misma manera; en una escritura de asignación, en cambio, se informa en data.notification. |
| 500 | internal_error | Error inesperado del servidor. En POST /products/{id}/notifications, cada 500 libera la Idempotency-Key, así que reintenta la misma solicitud con la misma clave. Allí hay tres casos previstos: Shopify no pudo devolver los metacampos del producto para la nota, Shopify no pudo confirmar los variant_ids solicitados, o la creación esperó más de 8 segundos detrás de las demás creaciones de la tienda. Si el intento fallido sí llegó a poner la campaña en cola, el reintento se rechaza con 429 notification_cooldown en lugar de iniciar una segunda. |
Documentación de la API
¿Te ha resultado útil?
Última actualización 2026-10-20