Errores

Traducida del inglés. Si hay alguna diferencia, la página en inglés es la referencia. Leer en inglés

Todas las respuestas de error tienen la misma forma:

{
  "error": {
    "type": "invalid_request_error",
    "code": "photo_required_for_channel",
    "message": "Product 66a1… has no images: channel \"etsy\" requires at least one image. Add an image, then publish again.",
    "param": null,
    "doc_url": "https://developers.nembol.com/docs/getting-started/errors#photo_required_for_channel"
  },
  "request_id": "req_9f83…"
}

type: una de cuatro familias (ver abajo). Úsalo para decidir la lógica de reintentos.
code: cadena estable y legible por máquina. Úsalo para gestionar casos concretos.
message: legible por personas, en inglés, te dice cómo corregirlo. Nunca lo parsees.
param: el campo problemático en los errores de validación (p. ej. variants[2].price).
request_id: inclúyelo cuando contactes con soporte.

Tipos de error

`type`	HTTP	¿Reintentar?
`invalid_request_error`	400, 402, 403, 404, 409, 410, 412, 413, 415, 422	No. Corrige la petición (402: la suscripción de la tienda no está activa)
`authentication_error`	401, 403	No. Corrige la clave o los scopes
`rate_limit_error`	429	Sí, después de `Retry-After` segundos
`api_error`	5xx	Sí, con backoff exponencial

Códigos comunes

Código	HTTP	Significado
`invalid_api_key`	401	Clave ausente, mal formada, revocada o rotada
`insufficient_scope`	403	A la clave le falta el scope de este endpoint
`plan_not_eligible`	403	El plan de la tienda no incluye acceso a la API (durante la prueba: solo funcionan las claves de prueba)
`product_not_found` / `order_not_found` / `variant_not_found` / `listing_not_found` / `action_not_found` / `operation_not_found` / `event_not_found` / `import_not_found` / `channel_account_not_found` / `channel_connection_not_found` / `ignored_listing_not_found` / `webhook_endpoint_not_found` / `redirect_url_not_found` / `promotion_not_found` / `discount_not_found` / `bundle_not_found` / `notification_not_found`	404	No existe ese recurso en esta tienda. `listing_not_found` también aparece por elemento en los resultados de anuncios por lotes
`validation_failed`	422	Consulta `param` y `message`
`invalid_json`	400	El cuerpo no es un JSON válido (falta una comilla, una coma o un corchete). No se ha leído ni cambiado nada
`payload_too_large`	413	El cuerpo supera los 25 MB. Envía las imágenes como URL o mediante `POST /files`, o divide el lote
`unsupported_encoding`	415	El charset o la codificación del cuerpo no son compatibles. Envía JSON en UTF-8 (gzip está bien)
`subscription_inactive`	402	La suscripción a Nembol de la tienda no está activa: no se pueden conectar ni desconectar canales (`POST /channel_connections`, `POST /channel_accounts/{id}/disconnect`). El mismo código puede llegar en `return_url` al abrir el enlace
`photo_required_for_channel`	422	Publicar un producto sin imágenes en un canal que exige imágenes
`billing_managed_by_nembol`	409	Un enlace de facturación en una tienda facturada directamente por Nembol (`billing_source: "manual"`): los cambios se gestionan a través de billing@nembol.com
`no_items_applied`	422	`POST /inventory/batch` y `POST /products/batch`: no se ha podido aplicar ningún elemento (todos los SKU son desconocidos, ambiguos, de un producto que requiere atención, o no válidos). Los motivos están en `error.details.rejected_items`; no ha cambiado nada
`image_unreachable`	422	No se ha podido descargar la `url` de una imagen (el host la rechazó o la URL es incorrecta; `param` indica qué imagen). Usa una URL pública o envía el archivo como `base64`
`channel_not_connected`	422	Publicar/retirar, o una promoción, en un canal que la tienda no ha conectado
`not_supported_for_channel`	422	Este endpoint solo funciona con algunos canales. El mensaje los indica
`setting_not_supported`	422	Ese ajuste no existe en esta cuenta de canal. Su array `writable` lista lo que se puede cambiar
`trial_publish_limit`	403	Se ha alcanzado el límite de publicaciones de la prueba en este canal. También por elemento en los resultados de anuncios por lotes. Suscríbete para publicar más
`sku_not_found` / `sku_ambiguous`	422	Elemento del lote rechazado (`/inventory/batch`, `/products/batch`): SKU desconocido, o un SKU en más de una variante (`error.details.product_ids` las lista; no se escribe nada). Corrige el duplicado o actualiza por id
`images_unsupported_on_batch_update`	per-item	El elemento del lote coincidió con un producto existente pero envió `images`. Actualiza sus imágenes con `PATCH /products/{id}`
`file_too_large` / `unsupported_file_type`	422	Una imagen (`POST /files`, o `images[]` como `base64` o `url`) supera los 10 MB, o no es JPEG, PNG, WebP ni GIF, p. ej. una URL que responde con una página HTML. `param` indica qué imagen
`idempotency_key_reused`	409	El mismo `Idempotency-Key` con un payload distinto
`idempotency_key_in_flight`	409	La primera petición con este `Idempotency-Key` todavía está en curso. Reintenta en breve
`precondition_failed`	412	`expected_updated_at` no coincide. Vuelve a leer y reintenta
`product_still_listed`	422	Eliminación rechazada: el producto todavía tiene anuncios activos. Retíralos primero
`order_not_fulfillable`	422	El pedido está cancelado/reembolsado y no se puede marcar como enviado
`channel_notification_unsupported`	422	Este canal no puede recibir avisos de envío. Reintenta con `notify_channel: false`
`overrides_not_supported`	422	Por ahora solo se pueden definir `overrides.title` / `overrides.description` en un anuncio. Un cuerpo vacío vuelve a sincronizar
`listing_not_delistable`	422	Los anuncios importados/vinculados pertenecen al canal
`listing_operation_in_progress`	409	Espera a que termine la operación en curso y reintenta
`not_started`	per-item	Resultado de la operación: el trabajo en el canal no pudo empezar porque otra operación tomó el anuncio. Reintenta
`no_price` / `price_below_minimum`	per-item	Resultado del ajuste de precio: el producto no tiene variantes con precio, o el nuevo precio quedaría por debajo del mínimo. No ha cambiado nada en ese producto
`channel_error`	n/a	(en los `issues[]` de un anuncio) el canal rechazó la última escritura. El mensaje es el error del canal. Filtra con `error_contains`
`import_not_supported`	422	No se pueden importar productos desde este canal
`import_already_running`	409	Ya hay una importación desde esta cuenta de canal, o una importación CSV, en cola o en curso. Espera a que termine
`import_still_running` / `import_already_undone`	409	Deshacer importación: la importación todavía no ha terminado, o ya se deshizo
`promotion_reaches_nothing`	422	Promociones: ninguno de los productos está publicado en los canales elegidos, así que no descontaría nada. Publícalos primero, o guárdala como borrador
`promotion_conflict`	409	Algunos productos ya están en otra promoción activa. Consulta `error.details.product_ids` y `promotion_ids`
`promotion_limit_reached`	403	Basic (y una prueba gratuita) ejecuta una promoción a la vez (activa o programada; los borradores no cuentan); Pro y superiores no tienen límite. Consulta `limits.running_promotions` en `GET /billing`. Detén la otra o mejora tu plan
`unknown_channel`	422	Promociones: un canal en `channels` en el que las promociones no funcionan. El mensaje lo indica y lista los válidos
`discount_exceeds_price`	422	Promociones: un descuento fijo no es inferior a un precio cubierto. `error.details` indica `product_id`, `variant_id`, `channel` y `price`
`promotion_running` / `promotion_not_running` / `promotion_reverting`	409	Promociones: editar o eliminar mientras está en curso (detenla primero); detener una que no está en curso; eliminar mientras los precios de los canales todavía se están restaurando (reintenta en breve)
`plan_upgrade_required`	403	Storefront: el plan de la tienda no incluye esta función
`code_exists`	409	Storefront: ya existe un descuento con este código (`param: code`)
`transition_not_allowed`	409	Pedido del storefront: el pedido no puede pasar de su estado actual al solicitado
`already_refunded` / `order_not_paid`	409	Reembolso de un pedido del storefront: no queda nada por reembolsar, o el pedido nunca se pagó. Se responde antes de cualquier confirmación
`stripe_refund_failed` / `paypal_refund_failed`	502	Reembolso de un pedido del storefront: el proveedor de pagos lo rechazó; el mensaje indica el motivo
`sku_required` / `title_required`	per-item	Al elemento del lote le falta el SKU con el que buscar coincidencias / un título con el que crearlo
`route_not_found`	404	No existe ese endpoint. Consulta la referencia
`rate_limit_exceeded`	429	Bucket vacío. Respeta `Retry-After`
`write_quota_exceeded`	429	Se ha alcanzado la cuota diaria de escrituras en los canales
`internal_error`	500	Algo ha fallado por nuestra parte. Reintenta con backoff; indica el `request_id` si persiste
`channel_unavailable`	502	El canal no respondió o falló. Reintenta más tarde
`confirmation_required`	409	Acción irreversible: muestra `confirmation.summary` y repite la misma petición con `Nembol-Confirmation`. Consulta Deshacer y confirmaciones
`confirmation_invalid`	409	El token de confirmación ya se usó, caducó o es de otra petición. En la respuesta viene uno nuevo
`undo_conflict`	409	No se ha deshecho nada: todos los valores se han vuelto a cambiar desde entonces. Consulta `error.details`
`action_already_undone`	409	La acción ya se deshizo
`not_reversible`	422	La acción no se puede deshacer; el mensaje indica qué hacer en su lugar
`undo_window_expired`	422	Las acciones se pueden deshacer durante 30 días
`product_not_deleted`	409	Se llamó a restore sobre un producto que no está eliminado
`product_requires_attention`	409	El producto está en `to_verify`: resuélvelo (`POST /products/{id}/resolve` o una fusión) antes de escribir sus anuncios
`product_not_requiring_attention`	409	Se llamó a resolve sobre un producto que no está en `to_verify`
`resolution_not_applicable`	409	Esa resolución no encaja con el `requires_attention.reason` del producto
`still_requires_attention`	409	`recheck`: el ajuste del canal todavía no está corregido. Consulta `error.details.reason`
`confirm_different`	409	Fusión: los productos no se parecen. Revisa `error.details.product_ids` y luego envía `confirm_different: true`
`same_channel_account`	422	Fusión: dos productos están activos en la misma cuenta de canal. Consulta `error.details.channels`
`variants_differ`	422	Fusión: las variantes no se corresponden. Emparéjalas con `variant_maps` usando `error.details.matching`
`invalid_choices` / `too_few` / `too_many`	422	Fusión: una entrada de `choices` no encaja, o no hay entre 2 y 10 productos
`product_merged`	409	Restauración rechazada: el producto se fusionó. Deshaz la fusión en su lugar
`not_a_partner`	403	`Nembol-Account` o endpoints de partner usados por una tienda que no es partner
`not_on_a_sub_account`	400	Has enviado `Nembol-Account` a un endpoint de partner (`/accounts`, `/partner/*`). Esos funcionan sobre tu propia cuenta de partner: llámalos sin el header
`sandbox_limit`	409	Un partner en sandbox ha alcanzado su máximo de empresas abiertas. Cierra una primero
`plan_too_small`	409	La empresa tiene más productos o cuentas de canal de los que permite el nuevo plan
`account_not_found`	404	No hay ninguna empresa con ese id para tu clave de partner
`billed_by_partner`	409	Se llamó a `/billing` dentro de una empresa: las empresas se facturan al partner
`billing_managed_elsewhere`	422	La tienda se factura a través de Shopify, Wix o WooCommerce.com. Cambia, cancela o actualiza el pago allí
`return_url_not_allowed`	422	`return_url` debe empezar por una URL registrada para esta tienda (`POST /redirect_urls`)
`plan_limits_exceeded`	422	Cambio de plan: la tienda usa más de lo que permite el plan de destino. Reduce el uso o elige un plan mayor
`no_payment_method_yet` / `no_subscription_yet`	422	La tienda todavía no tiene facturación con Stripe. Suscríbete primero con `POST /billing/plan_change_link`
`already_canceled` / `already_canceling` / `nothing_to_cancel`	422	Cancelar: la suscripción ya está cancelada, ya termina al final del periodo, o no hay nada que cancelar (prueba, sin suscripción de Stripe)
`trial_not_available`	422	La tienda no puede reiniciar una prueba
`billing_provider_error`	502	Stripe o PayPal no devolvieron una página. 409 cuando PayPal rechaza el cambio. Reintenta más tarde
`billing_links_unavailable`	503	Los enlaces de facturación todavía no están disponibles. Gestiona la suscripción desde el panel de Nembol
`account_suspended` / `account_closed`	409	Escrituras en una empresa suspendida (factura de partner vencida) o cerrada
`product_limit_reached`	409	Se ha alcanzado el límite de productos del plan de la empresa. Cambia su plan o elimina productos
`channel_slots_full`	422	No queda ninguna plaza libre para este canal. Desconecta primero una cuenta
`plan_channel_not_included`	403	El plan de la tienda no incluye este canal. Mejora tu plan para conectarlo
`channel_not_disconnectable`	422	La tienda paga su suscripción a Nembol a través de esta cuenta, así que no se puede desconectar
`connection_not_awaiting_choice`	409	`choose` sobre una conexión que no está en `needs_choice`
`choice_expired`	410	Ha pasado más de una hora desde que el vendedor inició sesión. Crea un enlace nuevo
`link_expired` / `link_already_used`	n/a	(en `return_url`) el enlace de conexión caducó o ya se usó. Crea uno nuevo
`different_channel_account`	n/a	(en `connection.error` y en `return_url`) el vendedor inició sesión en una tienda distinta de la que se está reconectando (`channel_account_id`, o una cuenta desconectada que se recupera: `reconnects_shop`). No ha cambiado nada. Inicia sesión en esa tienda, o conecta la nueva con `new_account: true` (sin `channel_account_id`)
`channel_login_failed`	n/a	(en `return_url` y en `connection.error`) el inicio de sesión en el canal no empezó o no se completó. Crea un enlace nuevo
`channel_credentials_rejected`	n/a	(en `connection.error`) el canal rechazó las credenciales enviadas
`plan_not_eligible` / `subscription_inactive` / `slot_no_longer_available`	n/a	(en `return_url`, error de conexión) la tienda ya no puede conectar ese canal
`no_account_to_connect`	n/a	(error de conexión) la cuenta de canal del vendedor no tiene nada que Nembol pueda conectar

Con el tiempo se añaden códigos nuevos; gestiona los códigos desconocidos recurriendo a type.

Última actualización el 21 de octubre de 2026

¿Necesitas ayuda?

Escríbenos y te responde una persona, normalmente en un día laborable.

Escríbenos Estado de la API

Tipos de error

Códigos comunes

En esta página