Respuestas y errores

Respuesta correcta

Toda respuesta correcta tiene la misma forma:

{
  "success": true,
  "message": "Información procesada de forma correcta.",
  "data": {}
}

Clave	Qué trae
success	Siempre true
message	Texto informativo. No lo uses para decidir nada: puede cambiar
data	El resultado: un objeto, una lista o null si la operación no devuelve datos

Listados paginados

Los listados paginados añaden links y meta:

{
  "success": true,
  "message": "Información procesada de forma correcta.",
  "data": [],
  "links": { "first": "…?page=1", "last": "…?page=4", "prev": null, "next": "…?page=2" },
  "meta": { "current_page": 1, "last_page": 4, "per_page": 12, "total": 45 }
}

Para pedir otra página, añade page a la petición.

Respuesta de error

Todo error tiene la misma forma:

{
  "success": false,
  "code": "PRODUCT_NOT_FOUND",
  "message": "El producto seleccionado no existe o no está disponible en la tienda.",
  "errors": {}
}

Clave	Qué trae
success	Siempre false
code	Identificador estable del error. Programa contra este valor
message	Texto para mostrar a una persona. Puede cambiar de redacción
errors	Solo en los datos inválidos: cada campo con sus mensajes. En los demás casos, un objeto vacío
reference	Solo en los fallos del servidor: el identificador para reportarlo

Datos inválidos

{
  "success": false,
  "code": "VALIDATION_ERROR",
  "message": "El campo titular es obligatorio.",
  "errors": {
    "titular": ["El campo titular es obligatorio."],
    "expiration_date": ["La tarjeta está caducada."]
  }
}

message repite el primer error, para mostrarlo como aviso. Usa errors para marcar cada campo del formulario.

Fallo del servidor

{
  "success": false,
  "code": "INTERNAL_ERROR",
  "message": "Ha ocurrido un error inesperado. Si vuelve a pasar, indicanos esta referencia: A1B2C3D4.",
  "errors": {},
  "reference": "A1B2C3D4"
}

El detalle técnico no se envía nunca. Al reportar el fallo, indica el valor de reference.

De quién es el error

HTTP	Quién lo resuelve	Qué hacer
400, 401, 403, 404, 409, 422	Quien llama	Corregir el dato, iniciar sesión o cambiar lo que se pide. Reintentar sin cambios no sirve
429	Quien llama	Esperar lo que indica Retry-After. Ver límites
503	La empresa o un servicio externo	Reintentar más tarde. Si el código es STORE_NOT_CONFIGURED, avisar a la tienda
500	Geor	Reportar la reference

Catálogo de códigos

Códigos generales

Salen cuando el error no tiene un código propio.

Código	HTTP	Qué pasó
BAD_REQUEST	400	Petición no válida
UNAUTHENTICATED	401	Falta la sesión o el token no vale
FORBIDDEN	403	Sin permiso para esta acción
NOT_FOUND	404	No existe
METHOD_NOT_ALLOWED	405	Método HTTP equivocado para esta ruta
CONFLICT	409	El estado actual no permite la acción
VALIDATION_ERROR	422	Datos inválidos. El detalle está en errors
RATE_LIMITED	429	Demasiadas peticiones
INTERNAL_ERROR	500	Fallo del servidor
SERVICE_UNAVAILABLE	503	Servicio no disponible
SESSION_EXPIRED	401	La sesión caducó
TOKEN_INVALID	401	El token de sesión fue rechazado

Acceso y tienda

Código	HTTP	Qué pasó	Qué hacer
INVALID_CREDENTIALS	401	Email o contraseña incorrectos	Revisar las credenciales
NOT_A_STORE_USER	403	La cuenta no es de cliente de la tienda	Usar una cuenta de cliente
ACCOUNT_NOT_VERIFIED	403	La cuenta aún no está verificada	Verificar el email o el teléfono
STORE_NOT_FOUND	404	La tienda no existe o no está publicada	—
STORE_PAUSED	503	La tienda está pausada	Reintentar más tarde
STORE_NOT_CONFIGURED	503	A la tienda le falta configuración: almacén o serie de pedidos	Avisar a la tienda

Catálogo

Código	HTTP	Qué pasó	Qué hacer
PRODUCT_NOT_FOUND	404	El producto no existe o no está en la tienda	—
PRODUCT_NOT_AVAILABLE	422	El producto no está a la venta	Quitarlo del carrito
CATEGORY_NOT_FOUND	404	La categoría no existe o no está disponible	—
LEGAL_INFO_NOT_FOUND	404	No hay un texto legal con ese código	—

Carrito y envío

Código	HTTP	Qué pasó	Qué hacer
CART_IDENTIFIER_REQUIRED	400	Falta el identificador del carrito	Enviar la cabecera user-ip-address con un valor propio de cada visitante (un UUID)
CART_NOT_FOUND	404	No hay carrito activo	Añadir un producto primero
CART_ITEM_NOT_FOUND	404	El producto no está en el carrito	—
CART_EMPTY	422	El carrito no tiene productos	Añadir productos
CART_ALREADY_PAID	409	El carrito ya se pagó y no se puede modificar	Iniciar un carrito nuevo
CART_NOT_EDITABLE	409	El carrito ya no está activo (por ejemplo, anulado) y no se puede modificar	Iniciar un carrito nuevo
OUT_OF_STOCK	409	No hay stock suficiente. El mensaje dice de qué producto	Reducir la cantidad o quitar el producto
SHIPPING_METHOD_INVALID	422	El tipo de envío no es válido	Usar uno de shippings/availables
SHIPPING_AREA_NOT_COVERED	422	El envío no llega a esa zona	Elegir otro tipo de envío o destino
UBIGEO_REQUIRED	422	Falta el destino	Enviar el ubigeo o iniciar sesión
DESTINATION_NOT_FOUND	422	El destino indicado no existe	Revisar el ubigeo
DEFAULT_ADDRESS_MISSING	422	El cliente no tiene dirección por defecto	Añadir una, o enviar el ubigeo
DEFAULT_ADDRESS_INCOMPLETE	422	La dirección por defecto no tiene destino	Editarla, o enviar el ubigeo
BILLING_NAME_REQUIRED	422	Falta el nombre o la razón social para el comprobante	Enviarlo con los datos de facturación

Cupones

Código	HTTP	Qué pasó	Qué hacer
COUPON_NOT_FOUND	422	El cupón no existe	Revisar el código
COUPON_EXPIRED	422	El cupón no está vigente	—
COUPON_LOGIN_REQUIRED	401	Este cupón exige sesión	Iniciar sesión
COUPON_ALREADY_USED	422	El cliente ya usó este cupón	—
COUPON_USER_NOT_ELIGIBLE	422	El cupón no es para este cliente	—
COUPON_REQUIRES_CART	422	El cupón es válido, pero hace falta un carrito para calcular el descuento	Añadir productos
COUPON_PRODUCTS_NOT_IN_CART	422	El carrito no tiene ningún producto de la promoción	Añadir uno
COUPON_MIN_AMOUNT_NOT_REACHED	422	No se llega al importe mínimo	Añadir productos
COUPON_MAX_AMOUNT_EXCEEDED	422	Se supera el importe máximo	Quitar productos

Pedidos

Código	HTTP	Qué pasó	Qué hacer
ORDER_NOT_FOUND	404	El pedido no existe	—
ORDER_ALREADY_CANCELLED	409	El pedido ya estaba anulado	—
ORDER_CANNOT_BE_CANCELLED	409	El pedido ya está en un estado que no permite anularlo	Contactar con la tienda
ORDER_VOUCHER_ALREADY_ATTACHED	409	El pedido ya tiene un comprobante adjunto (pantalla del ERP)	—
ORDER_STATUS_TRANSITION_INVALID	422	No se puede pasar el pedido a ese estado (pantalla del ERP)	—

Cuenta

Código	HTTP	Qué pasó	Qué hacer
USER_NOT_FOUND	404	No hay ningún cliente con ese email o teléfono	Revisar el dato o registrarse
EMAIL_ALREADY_IN_USE	409	El email ya lo usa otro cliente	Usar otro
PHONE_ALREADY_IN_USE	409	El teléfono ya lo usa otro cliente	Usar otro
CURRENT_PASSWORD_INCORRECT	422	La contraseña actual no es correcta	Revisarla
PHONE_NOT_REGISTERED	422	La cuenta no tiene teléfono	Añadirlo en el perfil
COUNTRY_INVALID	422	El país no existe o no es válido	Revisar el país
COUNTRY_PHONE_CODE_MISSING	422	El país no tiene prefijo telefónico configurado	Avisar a la tienda
ACCOUNT_ALREADY_VERIFIED	409	La cuenta ya está verificada	—
EMAIL_ALREADY_VERIFIED	409	El email ya está verificado	—
PHONE_ALREADY_VERIFIED	409	El teléfono ya está verificado	—
ACCOUNT_HAS_RECORDS	409	La cuenta tiene datos en la empresa y no se puede borrar	Contactar con la tienda

Códigos de verificación y recuperación de contraseña

Código	HTTP	Qué pasó	Qué hacer
VERIFICATION_NOT_FOUND	404	No hay ningún código pendiente	Pedir uno nuevo
VERIFICATION_EXPIRED	422	El código caducó	Pedir uno nuevo
VERIFICATION_CODE_INVALID	422	El código es incorrecto	Revisarlo. Cada intento cuenta
VERIFICATION_TOO_MANY_ATTEMPTS	422	Demasiados intentos: la solicitud se anuló	Pedir un código nuevo
RESET_REQUEST_NOT_FOUND	404	No hay ninguna solicitud de cambio de contraseña	Pedir un código
RESET_REQUEST_EXPIRED	422	La solicitud caducó	Pedir un código nuevo
RESEND_TOO_SOON	429	Aún no se puede pedir otro código	Esperar unos segundos

Consulta de DNI y RUC

Código	HTTP	Qué pasó	Qué hacer
DOCUMENT_TYPE_INVALID	422	Solo se consultan DNI y RUC	—
DOCUMENT_NUMBER_INVALID	422	El número no tiene las cifras correctas (8 el DNI, 11 el RUC)	Revisarlo
DOCUMENT_NOT_FOUND	404	No se encontró el documento	Revisar el número
LOOKUP_SERVICE_UNAVAILABLE	503	El servicio de consulta no responde	Reintentar más tarde

Datos del comprador

Código	HTTP	Qué pasó
ADDRESS_NOT_FOUND	404	La dirección no existe o no es del cliente
BILLING_NOT_FOUND	404	Los datos de facturación no existen o no son del cliente
CARD_NOT_FOUND	404	La tarjeta no existe o no es del cliente
RECIPIENT_NOT_FOUND	404	El destinatario no existe o no es del cliente
FAVORITE_ALREADY_EXISTS	409	El producto ya está en favoritos
FAVORITE_NOT_FOUND	404	El producto no está en favoritos