Errores

La API usa un envelope JSON estable para errores.

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "The products field is required.",
    "details": {}
  },
  "meta": {
    "api_version": "2026-04"
  }
}

Códigos de estado habituales

Estado	Significado
200	Request completada correctamente.
201	Recurso u operación batch aceptada/creada.
400	Falta la versión API en una request a la API fechada.
401	API key ausente, inválida o desactivada.
403	IP o API key bloqueada por reglas de protección.
404	Recurso o versión API no encontrados.
405	Método HTTP no permitido para el endpoint.
409	La request entra en conflicto con un estado que la API ya tenía registrado.
422	La request era JSON válido, pero falló la validación.
429	Límite de uso superado.
500	Error inesperado en Revi.

Códigos de error habituales

Código	Cuándo aparece
authentication_required	Falta el header X-API-KEY.
invalid_api_key	La API key no existe o está desactivada.
invalid_version	La versión fechada de API no existe.
version_sunset	La versión fechada solicitada ha sido retirada.
validation_error	Un campo, filtro, enum o forma de payload no es válido.
not_found	El recurso solicitado no existe para el contexto de la API key.
method_not_allowed	La ruta existe pero no soporta el método HTTP usado.
server_error	Se produjo un error inesperado en Revi.
version_unavailable	La versión fechada existe, pero no está habilitada en este entorno.
invalid_token	La credencial Bearer falta, está mal formada, ha caducado o ha sido revocada.
insufficient_scope	El cliente API no tiene el scope que exige la operación.
connection_not_found	La conexión no existe, está inactiva, pertenece a otra tienda o no está concedida al cliente.

Conflictos de revisión e idempotencia

Las operaciones de estado fuente y de backfill son ordenadas e idempotentes: cada escritura lleva una revisión, un ID de evento o una clave de idempotencia. Cuando una escritura contradice lo que la API ya registró bajo el mismo identificador, se rechaza con 409 en vez de sobrescribir el estado almacenado.

Código	Cuándo aparece
stale_catalog_revision	La catalog_revision enviada es menor que la revisión ya almacenada para la conexión.
catalog_revision_payload_conflict	Esa catalog_revision ya se registró con un catálogo de estados distinto. Reenviarla con el catálogo idéntico deduplica en lugar de fallar.
stale_source_revision	La revision del pedido es menor o igual que la revisión ya almacenada para ese pedido, bajo un event_id nuevo.
source_event_payload_conflict	Ese event_id ya se registró con contenido distinto. Reenviarlo con el contenido idéntico deduplica en lugar de fallar.
idempotency_payload_conflict	Esa Idempotency-Key ya se usó para un backfill con un payload distinto.

Cómo debe reaccionar un cliente

• Un 409 nunca se resuelve reintentando la misma request con el mismo contenido y esperando otro resultado. Reintentar una request idéntica tras un timeout sí es seguro y devuelve el resultado ya almacenado: eso no produce conflicto.
• Trata una revisión obsoleta como «otro escritor va por delante de mí». Relee el estado actual y envía la siguiente transición con una revisión estrictamente mayor. No decrementes ni reinicies el contador de revisiones para forzar la escritura.
• Trata un conflicto de payload como un bug del cliente: se reutilizó el mismo identificador para contenido distinto. Corrige el identificador —genera un event_id o una Idempotency-Key nuevos para contenido realmente nuevo— en lugar de cambiar el contenido asociado a un identificador ya aceptado.
• No reenvíes un backfill con una Idempotency-Key nueva solo para esquivar el conflicto: puede duplicar trabajo. Comprueba antes qué registró la clave anterior.
• No reintentes un 409 en bucle ni con backoff. Es un resultado determinista y seguirá fallando hasta que cambie la revisión o el identificador.

Otros conflictos

Código	Cuándo aparece
recipient_optout_revocation_requires_review	Un negocio ha intentado revocar por API la baja de un destinatario. Nunca se concede de forma automática: se exige consentimiento renovado documentado y revisión de Soporte.

Este conflicto también es determinista. No lo reintentes: contacta con Soporte aportando la evidencia del consentimiento renovado.

Los errores de límite de uso usan la respuesta 429 documentada en Límites de uso y pueden no incluir el envelope estándar con success.

Recomendaciones para clientes

• Trata success: false como fallo aunque el status HTTP sea 200.
• Revisa Retry-After en respuestas 429.
• Registra error.code en las peticiones API.
• Oculta API keys y emails de clientes en los logs.