Errores

Todo error de la API pública tiene la misma forma, y toda respuesta (también las exitosas) trae la cabecera X-Request-Id:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "La petición no cumple el formato.",
    "details": [{ "field": "items.0.stock", "issue": "must not be less than 0" }]
  },
  "request_id": "5b1f0c1e-7c1a-4a8e-9d51-2d8d3f0a9c11"
}

Puedes mandar tu propio X-Request-Id (hasta 100 caracteres: letras, números, . _ : -) para seguir una petición de punta a punta; si no, papedir genera uno. Cítalo al pedir soporte.

HTTP	code	Qué pasó	¿Reintentar?
400	VALIDATION_FAILED	El cuerpo o los parámetros no cumplen el formato (details dice qué campo)	No, corrige
400	IDEMPOTENCY_KEY_REQUIRED	Falta o está mal la cabecera Idempotency-Key	No, corrige
400	EXTERNAL_STOCK_TOO_MANY_ITEMS	Más de 500 productos en un lote	No, divide el lote
401	INVALID_API_KEY	Falta la llave, no tiene la forma pdk_live_… o no existe	No
401	API_KEY_REVOKED	La llave fue revocada	No, pide otra
403	MODULE_DISABLED	El negocio no tiene activo el inventario externo	No
403	INSUFFICIENT_SCOPE	La llave no tiene el scope (details dice cuál)	No
403	INTEGRATION_DISABLED	El negocio pausó la integración (solo escrituras)	Más tarde
409	EXTERNAL_ID_TAKEN	Otro cruce simultáneo tomó el mismo external_id	Sí
429	RATE_LIMITED	Pasaste el límite de la ruta	Sí, después de los segundos de Retry-After
500	INTERNAL_ERROR	Error de papedir	Sí, con espera exponencial

Un resultado por ítem (not_found, stale…) no es un error: la petición fue exitosa (200) y el detalle va en results. Ver la guía de inventario externo.