Gestionar errores y reintentos

Los errores aparecen en tres lugares distintos. Organiza tu gestión según cuál de ellos estés mirando.

1. Errores de la solicitud (estado HTTP + envoltorio)

Validación, autenticación y límites de solicitudes. Son síncronos, en el envoltorio de error. Decide según error.type la política de reintentos y según error.code los detalles. 429 → espera Retry-After; 5xx → backoff exponencial con el mismo Idempotency-Key.

2. Errores del canal (los issues[] del anuncio)

La solicitud era correcta, pero el canal rechazó el anuncio más tarde, de forma asíncrona. El anuncio pasa a status: "error" y issues[] contiene el mensaje propio del canal en texto plano (por ejemplo, "You are currently in a Shop probation period…"). Son problemas del vendedor, no de la API: muéstraselos al comerciante.

Corrige primero la causa y después reintenta solo los anuncios que fallan con ese error. error_contains busca en el mensaje de error actual del anuncio:

curl "https://api.nembol.com/rest/v1/listings?error_contains=item%20specific%20Brand" \
  -H "Authorization: Bearer $NEMBOL_API_KEY"

Después reintenta exactamente esos, hasta 100 por llamada:

curl -X POST https://api.nembol.com/rest/v1/listings/batch \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "retry",
       "items": [{"product_id": "prod_66a1f0", "channel_account_id": "chac_6aa12cab"}]}'

Los anuncios que ya no están en error vuelven como skipped (not_in_error), así que una lista de reintentos desactualizada es inofensiva. Para un solo anuncio, PATCH /listings/{id} con {} lo resincroniza.

3. Resultados parciales (operaciones)

Las llamadas en lote devuelven una operación cuyos results[] son por elemento y canal. status: "partial" significa que algunos tuvieron éxito. Reintenta solo las entradas fallidas, nunca el lote entero a ciegas.

Puntos a tener en cuenta

• Nunca reintentes a ciegas. Filtra por el fallo exacto (error_contains, las filas fallidas de results[]). Los reintentos masivos de todos los anuncios en error amplifican los problemas.
• Idempotency-Key hace que los reintentos no cuesten nada. Misma clave + mismo payload = respuesta guardada, sin efectos dobles.
• Con el tiempo aparecerán códigos desconocidos. Recurre a error.type.
• request_id está en todos los errores: indícalo al contactar con soporte.

Última actualización el 20 de octubre de 2026