Saltar al contenido principal
Migo Docs

Catálogo de errores

Todos los códigos de error de negocio que pueden devolver las APIs de Migo. Los códigos son strings en el rango 7000–8099 y se devuelven en el arreglo errors[] del envelope CustomResponse:

{
"success": false,
"message": "Optional human-readable summary",
"errors": [{ "code": "7200", "message": "Card not found in the system." }]
}

El status HTTP se deriva del código en el interceptor de respuesta del gateway, con este orden de precedencia: 500 (interno) → 404 (no encontrado) → 400 (solicitud inválida) → 401 (no autenticado) → 403 (prohibido) → 409 (conflicto). Un código no clasificado en ningún conjunto usa 500 por defecto.

Fuente de verdad

Este catálogo se genera a partir de MigoCodeErrors y MigoErrorMessages en @migo-payments/ali-common-tl (src/errors/error.enum.ts y src/errors/error.ts). La columna Mensaje muestra la traducción al español; la API devuelve estas cadenas en inglés.

Envelope de respuesta​

Cada API de Migo devuelve respuestas envueltas en un envelope CustomResponse<T>. La forma del envelope es:

interface CustomResponse<T> {
success: boolean;
message?: string;
data?: T;
errors?: { code: string; message: string }[];
}

Nota que code es un string (p. ej. "7100"), y errors es un array de objetos { code, message }. No existe campo statusCode, error.name ni error.detail en el payload del wire — el name (p. ej. USER_NOT_FOUND) es la clave interna de MigoNameErrors, no parte del body de la respuesta.

Éxito​

{
"success": true,
"message": "ok",
"data": { "...": "..." }
}

Error​

{
"success": false,
"message": "Validation failed",
"errors": [
{
"code": "7100",
"message": "User not found in the system."
}
]
}

Mapeo de status codes​

HTTP statusCuándo se devuelve
200 OKÉxito (incluyendo jobs asíncronos que devuelven un id de batch/job en el body)
201 CreatedRecurso creado (p. ej. creación de estado de cuenta aceptada)
204 No ContentÉxito, sin body
400 Bad RequestValidación del cuerpo falló
401 UnauthorizedJWT faltante / vencido / inválido
403 ForbiddenAutenticado pero permiso denegado
404 Not FoundEl recurso no existe
409 ConflictConflicto de estado del recurso
422 Unprocessable EntityValidación semántica falló (p. ej. tarjeta vencida)
500 Internal Server ErrorBug de Migo — repórtalo con el timestamp y los detalles de la solicitud
502 Bad GatewayProcesador upstream inalcanzable
503 Service UnavailableMantenimiento programado o caída parcial
504 Gateway TimeoutTimeout del procesador upstream

Generales y parámetros (7000–7099)​

CódigoNombreHTTPMensaje
7000CHECK_PARAMETERS400Verifica los parámetros proporcionados.
7001GREATER_THAN_ZERO400El monto debe ser mayor que cero.
7002INVALID_FORMAT_AMOUNT400Formato de monto inválido.
7003CONSULT_WITH_SUPPORT500Contacta a soporte para recibir asistencia.
7004SERVICES_NOT_FOUND404Servicios requeridos no encontrados.
7005PROCESSOR_NOT_FOUND404Procesador de pago no encontrado.
7006EXTERNAL_ID_ALREADY_EXISTS409El ID externo ya existe.
7007ERROR_GETTING_ACTIONS500Error al obtener las acciones.
7008ERROR_DATE_RTU500La fecha RTU (actualización en tiempo real) es inválida. La fecha de actualización debe estar dentro de los últimos 6 meses a partir de la fecha actual.
7009ERROR_CAN_INVOICE_PARAM500Error con los parámetros de facturación.
7010NOT_FOUND404No encontrado, verifica el endpoint
7011ERROR_CREATE_TERMINAL_PROCESSOR500Error al crear el procesador de terminal, verifica los datos e inténtalo de nuevo.
7012ERROR_UPDATE_TERMINAL_PROCESSOR500Error al actualizar el procesador de terminal, verifica los datos e inténtalo de nuevo.
7013TERMINAL_PROCESSOR_NOT_FOUND404Procesador de terminal no encontrado
7014TERMINAL_PROCESSOR_EMPTY404La terminal no tiene un procesador de terminal
7015TERMINAL_PROCESSOR_ALREADY_EXISTS409El procesador de terminal ya existe
7016TERMINAL_PROCESSOR_INACTIVE409El procesador de terminal está inactivo; si deseas activarlo, contacta a soporte.

Usuarios, autenticación y OTP (7100–7199)​

CódigoNombreHTTPMensaje
7100USER_NOT_FOUND404Usuario no encontrado en el sistema.
7101USER_ALREDY_EXIST409El usuario ya existe en el sistema, verifica tu nombre de usuario.
7102USER_DOCUMENT_NOT_FOUND404Documento de usuario no encontrado.
7103ERROR_CREATE_USER_DOCUMENT500Error al crear el documento de usuario.
7104ERROR_READ_USER_FILE500Error al leer el archivo de usuario.
7105ERROR_CREATE_LEAD500Error al crear el lead.
7106ERROR_FIND_USER_BY_DOCUMENT500Error al buscar usuario por documento.
7107VERIFY_DOCUMENT_TYPE400Verifica el tipo de documento.
7108ACCOUNT_NOT_FOUND404Cuenta no encontrada en el sistema.
7109ERROR_CREATING_NEW_ACCOUNT500Error al crear la nueva cuenta.
7110ERROR_CREATING_INVITATION_CODE500Ocurrió un error al crear el código de invitación, verifica el estado de la sucursal
7111ERROR_PASSWORD_NOT_MATCH400Las contraseñas no coinciden, verifica e inténtalo de nuevo.
7112ERROR_MIN_LENGTH_PASSWORD400Verifica que la longitud de la cadena tenga el número de caracteres indicado.
7113ERROR_LOWERCASE_PASSWORD400Verifica que la cadena contenga al menos una letra minúscula.
7114ERROR_UPPERCASE_PASSWORD400Verifica que la cadena contenga al menos una letra mayúscula.
7115ERROR_AT_LEAST_NUMBER_PASSWORD400Verifica que la cadena contenga al menos un número.
7116ERROR_AT_LEAST_SYMBOL_PASSWORD400Verifica que la cadena contenga al menos un carácter especial.
7117INVALID_PASSWORD400Contraseña inválida, verifica e inténtalo de nuevo.
7118ERROR_CREATING_USER500Error al crear el usuario, contacta a soporte.
7119ERROR_PREVIOUS_PASSWORD409No puedes reutilizar una contraseña anterior, intenta con una nueva.
7120NOT_FOUND_INVITATION_CODE404Código de invitación no encontrado, verifica tu código e inténtalo de nuevo.
7121LEAD_ALREADY_REGISTERED409El lead ya está registrado, obtén un nuevo código de invitación.
7122TERMS_AND_CONDITIONS_NOT_ACCEPTED400Acepta los términos y condiciones para continuar.
7123DOCUMENT_ALREADY_EXIST409El documento ya existe, verifícalo.
7124ERROR_FINDING_USER500Error al buscar el usuario, verifica tu userId e inténtalo de nuevo.
7125ERROR_CREATING_USER_APPLICATION500Error al crear la aplicación del usuario, contacta a soporte.
7126ERROR_CREATING_AUTH_USER500Error al crear el usuario de autenticación, contacta a soporte.
7127ERROR_USER_IS_ACCOUNT400El usuario es una cuenta, acceso denegado.
7128USERNAME_NOT_FOUND404Usuario no encontrado, verifica tu nombre de usuario e inténtalo de nuevo.
7129APPLICATION_USER_NOT_FOUND404Usuario de aplicación no encontrado, verifica tu usuario e inténtalo de nuevo.
7130LEAD_NOT_FOUND404Lead no encontrado, verifica la información del lead e inténtalo de nuevo.
7131INVALID_OTP_PURPOSE400Propósito de OTP inválido, verifica el propósito e inténtalo de nuevo.
7132INVALID_OTP401OTP inválido, verifica el OTP e inténtalo de nuevo.
7133OTP_NOT_FOUND404OTP no encontrado, verifica el OTP e inténtalo de nuevo.
7134OTP_ALREADY_USED409El OTP ya fue utilizado, solicita un nuevo OTP.
7135OTP_EXPIRED400El OTP ha expirado, solicita un nuevo OTP.
7136OTP_REQUEST_FAILED400No se pudo solicitar el OTP, inténtalo más tarde.
7137ERROR_VALIDATING_USER500Error al validar el usuario, contacta a soporte.
7138ERROR_ACCESS_LOGIN500Ocurrió un error al iniciar sesión, inténtalo más tarde.
7139USER_SUSPENDED403Has superado el número de intentos de inicio de sesión, tu usuario ha sido suspendido temporalmente
7140ERROR_FINDING_SUSPENSION500Error al buscar la suspensión, verifica el ms de usuarios
7141ERROR_CREATING_SUSPENSION500Error al crear la suspensión, verifica el ms de usuarios
7142ERROR_LOGOUT500Error al cerrar sesión, verifica tu token
7143UNAUTHORIZED_ACCESS_USER401Acceso de usuario no autorizado, verifica tus credenciales.
7144FORBIDDEN_ACCESS_USER403Tu usuario no tiene permiso para acceder a este recurso
7145INVALID_USER_ACCESS_TOKEN500Token de acceso de usuario inválido, verifica tu token
7146INVALID_USER_REFRESH_TOKEN500Token de actualización de usuario inválido, verifica tu refresh token
7147INVALID_USER_SIGNATURE401Firma de usuario inválida, verifica tu token
7148EXPIRED_USER_TOKEN400Token de usuario expirado, usa el refresh token o inicia sesión de nuevo.
7149EXPIRED_USER_REFRESH_TOKEN400Refresh token de usuario expirado, inicia sesión de nuevo.
7150ERROR_CREATING_AUTH_USER_ROLE500Error al crear el rol del usuario de autenticación, contacta a soporte.
7151ERROR_CREATING_AUTH_USER_PERMISSION500Error al crear el permiso del usuario de autenticación, contacta a soporte.
7152ERROR_UPDATING_AUTH_USER_PERMISSION500Error al actualizar el permiso del usuario de autenticación, contacta a soporte.
7153ERROR_UPDATING_AUTH_USER_ROLE500Error al actualizar el rol del usuario de autenticación, contacta a soporte.
7154ERROR_FINDING_AUTH_USER_ROLE500Error al buscar el rol del usuario de autenticación, contacta a soporte.
7155ERROR_FINDING_AUTH_USER_PERMISSION500Error al buscar el permiso del usuario de autenticación, contacta a soporte.
7156AUTH_USER_ROLE_NOT_FOUND404Rol de usuario de autenticación no encontrado, verifica los nombres
7157AUTH_USER_PERMISSION_NOT_FOUND404Permiso de usuario de autenticación no encontrado, verifica los nombres
7158ROLE_ALREADY_EXIST409El rol ya existe, verifica los roles
7159USER_PERMISSION_ALREADY_EXIST409El permiso de usuario ya existe, verifica los datos e inténtalo de nuevo.
7160ERROR_REGISTERING_FCM_TOKEN500Error al registrar el token FCM, verifica los datos e inténtalo de nuevo.
7161ERROR_REMOVING_FCM_TOKEN500Error al eliminar el token FCM, verifica los datos e inténtalo de nuevo.
7162INVALID_REGISTRATION_TOKEN400Token de registro inválido, verifica los datos e inténtalo de nuevo.
7163FCM_TOKEN_NOT_FOUND404Token FCM no encontrado, renueva el token del dispositivo
7164ERROR_UPDATING_USER_PASSWORD500Error al actualizar la contraseña del usuario, verifica los datos e inténtalo de nuevo.
7165PASSWORD_NOT_PROVIDED500No se proporcionó una contraseña, proporciona una contraseña.
7166PASSWORDS_DO_NOT_MATCH500Las contraseñas no coinciden, verifica e inténtalo de nuevo.
7167ERROR_UPLOADING_PROFILE_IMAGE400Error al subir la imagen de perfil, inténtalo más tarde.
7168ERROR_GETTING_USER_PROFILE400Error al obtener el perfil del usuario, verifica tu userId e inténtalo de nuevo.
7169ERROR_UPDATING_USER_PROFILE500Error al actualizar el perfil del usuario, inténtalo más tarde.
7170ERROR_FETCHING_PROFILE_DATA500Error al obtener los datos del perfil, inténtalo más tarde.
7171INVALID_USER_STATUS409El estado del usuario es inválido; si deseas activarlo, contacta a soporte.
7172EXPIRED_USER_PASSWORD409La contraseña del usuario ha expirado, restablécela e inténtalo de nuevo.
7173SDK_NOT_VALID500SDK inválido.
7186USER_DOCUMENT_DUPLICATED_IN_MERCHANT409Más de un usuario está registrado con este documento, contacta a soporte.

Tarjetas (7200–7299)​

CódigoNombreHTTPMensaje
7200CARD_NOT_FOUND404Tarjeta no encontrada en el sistema.
7201INVALID_CARD_ACCESS400Acceso a la tarjeta no autorizado. Verifica la información ingresada.
7202ALREADY_ACTIVED409La tarjeta ya está activada.
7203ALREADY_BLOCKED409La tarjeta ya está bloqueada.
7204ALREADY_UNLOCKED409La tarjeta ya está desbloqueada.
7205INCORRECT_PIN400PIN ingresado incorrecto.
7206CARD_EXPIRED400La tarjeta ha expirado.
7207CARD_NOT_CREATED500Error al crear la tarjeta.
7208CARD_ALREADY_ASSIGNED409La tarjeta ya está asignada a un usuario.
7209CARD_ALREADY_LINKED409La tarjeta ya está vinculada a una cuenta.
7210CARD_NOT_UPDATED500Error al actualizar la información de la tarjeta.
7211ERROR_CREATING_CARD500Error al crear la tarjeta.
7212CARDS_NOT_FOUND404El usuario no tiene tarjetas.
7213INVALID_STATUS_CARD400El estado de la tarjeta es inválido. Verifica que tu tarjeta esté activa
7214ERROR_GETTING_CARD500Error al obtener la tarjeta, verifica tu cardId e inténtalo de nuevo.
7215ERROR_GETTING_USER_CARDS500Error al obtener las tarjetas del usuario, verifica tu userId e inténtalo de nuevo.
7216ERROR_CREATING_CARD_USER_PERMISSION500Error al crear el permiso de usuario de la tarjeta, verifica los ids y nombres e inténtalo de nuevo.
7217ERROR_UPDATING_CARD_USER_PERMISSION500Error al actualizar el permiso de usuario de la tarjeta, verifica los ids y nombres e inténtalo de nuevo.
7218ERROR_FINDING_CARD_USER_PERMISSION500Error al buscar el permiso de usuario de la tarjeta, verifica los ids y nombres e inténtalo de nuevo.
7219CARD_USER_PERMISSION_NOT_FOUND404Permiso de usuario de la tarjeta no encontrado, verifica los ids y nombres e inténtalo de nuevo.
7220THIRD_PARTY_CARD_NOT_FOUND404Tarjeta de terceros no encontrada, verifica el sufijo, nombre de usuario o id e inténtalo de nuevo.
7221ERROR_CREATING_THIRD_PARTY_CARD500Error al crear la tarjeta de terceros, verifica los datos e inténtalo de nuevo.
7222THIRD_PARTY_CARD_ALREADY_ASSIGNED409La tarjeta de terceros ya existe, verifica el sufijo y el nombre de usuario e inténtalo de nuevo.
7223CARD_ASSOCIATED_BELONGS_TO_THE_USER_WHO_MADE_THE_REQUEST409No puedes asociar tarjetas que ya pertenecen al usuario
7224ERROR_CREATING_VIEW_TOKEN500Error al crear el view token, verifica los datos e inténtalo de nuevo.
7225VIEW_TOKEN_NOT_FOUND404View token no encontrado, verifica los datos e inténtalo de nuevo.
7226ERROR_UNLINKED_THIRD_PARTY_CARD500Error al desvincular la tarjeta de terceros, verifica los datos e inténtalo de nuevo.
7227ERROR_UPDATING_THIRD_PARTY_CARD500Error al actualizar la tarjeta de terceros, verifica los datos e inténtalo de nuevo.

Transferencias y pagos (7300–7399)​

CódigoNombreHTTPMensaje
7300ERROR_CREATING_TRANSFER500Error al crear la transferencia.
7301ERROR_UPDATING_TRANSFER500Error al actualizar la transferencia.
7302ERROR_GETTING_HISTORY500Error al obtener el historial de transacciones.
7303INSUFFICIENT_FUNDS400Fondos insuficientes para completar la transacción.
7304INVALID_TRANSFER_STATUS400Estado de transferencia inválido.
7305ERROR_CREATING_TRANSFER_TYPE500Error al crear el tipo de transferencia.
7306CARD_TRANSFER_NOT_FOUND404Transferencia de tarjeta no encontrada.
7307ERROR_CREATING_TERMINAL_PAYMENT500Error al crear el pago de terminal.
7308ERROR_TERMINAL_PAYMENT_STATUS500Error al obtener el estado del pago de terminal.
7309ERROR_UPDATING_TERMINAL_PAYMENT500Error al actualizar el pago de terminal.
7310CARD_TRANSFER_DATE_NOT_VALID403La solicitud ya no es válida porque debe completarse dentro del mismo día calendario.
7311TOPUP_REASON_TOO_LONG400El motivo de la recarga es demasiado largo.

Terminales, negocios y sucursales (7400–7499)​

CódigoNombreHTTPMensaje
7400TERMINAL_NOT_FOUND404Terminal no encontrada.
7401TERMINAL_INACTIVE400La terminal está inactiva.
7402TERMINAL_PAYMENT_NOT_FOUND404Pago de terminal no encontrado.
7403ERROR_CREATING_TERMINAL500Error al crear la terminal.
7404ERROR_UPDATING_TERMINAL500Error al actualizar la terminal.
7405ERROR_CREATING_COMMERCE_CONFIG500Error al crear la configuración del comercio.
7406ERROR_CREATING_COMMERCE500Error al crear el comercio.
7407COMMERCE_OR_USER_NOT_FOUND404Comercio o usuario no encontrado.
7408BUSINESS_NOT_FOUND404Negocio no encontrado.
7409ERROR_CREATING_BRANCH500Error al crear la sucursal, contacta a soporte.
7410BRANCH_NOT_FOUND404Sucursal no encontrada
7411ERROR_CREATING_BRANCH_ACCOUNT500Ocurrió un error al crear la cuenta de la sucursal, verifica el estado de la sucursal y la existencia de la cuenta
7412BRANCH_ACCOUNT_NOT_FOUND404Cuenta de la sucursal no encontrada, verifica el estado de la sucursal
7413TERMINAL_ALREADY_LINKED409La terminal ya está vinculada, obtén una nueva terminal.
7414BUSINESS_ALREADY_EXISTS409El negocio ya existe, verifica los datos e inténtalo de nuevo.
7415BRANCH_ALREADY_EXISTS409La sucursal ya existe, verifica los datos e inténtalo de nuevo.
7416BRANCH_AUTH_USER_NOT_FOUND404El AuthUserId proporcionado no existe en el usuario de autenticación de la sucursal, verifica la información.
7417BRANCH_AUTH_USER_OWNER_NOT_FOUND404La sucursal proporcionada no tiene propietario, verifica la información.
7418ERROR_FINDING_BRANCH_AUTH_USER500Error al obtener el usuario de autenticación de la sucursal, contacta a soporte.
7419TERMINAID_OR_DEVICEID_ARE_MISSING400Falta el ID de terminal o el ID de dispositivo, verifica los datos e inténtalo de nuevo.

Liquidaciones y régimen (7500–7599)​

CódigoNombreHTTPMensaje
7500ERROR_CREATING_SETTLEMENT500Error al crear la liquidación.
7501SETTLEMENT_NOT_FOUND404Liquidación no encontrada.
7502ERROR_UPDATING_SETTLEMENT500Error al actualizar la liquidación.
7503REGIME_NOT_VALID500Régimen fiscal inválido.
7504REGIME_NOT_FOUND404Régimen fiscal no encontrado.
7505ERROR_CREATING_REGIME500Error al crear el régimen fiscal.
7506ERROR_CREATING_ACCOUNT_CHANGE500Error al crear el cambio de cuenta.
7507DUPLICATE_SETTLEMENT500Ya existe una liquidación para el pago de terminal actual
7508CONFIG_NOT_FOUND404Configuración no encontrada
7509CALLBACK_NOT_FOUND404Callback no encontrado, verifica los datos e inténtalo de nuevo.
7510ERROR_GETTING_UNSETTLED_TERMINAL_PAYMENTS500Error al obtener los pagos de terminal no liquidados, verifica los datos e inténtalo de nuevo.

Clientes, roles, permisos y archivos (7600–7699)​

CódigoNombreHTTPMensaje
7600ERROR_CREATING_CLIENT500Error al crear el cliente, contacta a soporte.
7601ERROR_AUTHENTICATION_FAILED500La autenticación falló, verifica tus credenciales.
7602UNAUTHORIZED_ACCESS401Acceso no autorizado, verifica tus credenciales.
7603EXPIRED_TOKEN400Token expirado, usa el refresh token o inicia sesión de nuevo.
7604INVALID_SIGNATURE401Firma inválida, verifica tu token.
7605INVALID_REFRESH_TOKEN400Refresh token inválido, inicia sesión de nuevo.
7606INVALID_ACCESS_TOKEN400Token de acceso inválido, verifica tu token.
7607CLIENT_NOT_FOUND404Cliente no encontrado, verifica tu comercio.
7608ERRROR_CREATING_PERMISSION500Sin mensaje registrado — usa el fallback 7003 (contactar a soporte).
7609ERROR_CREATING_ROLE500Error al crear el rol, contacta a soporte.
7610ERROR_CREATING_ROLE_PERMISSION500Error al crear el permiso del rol, contacta a soporte.
7611ROLES_NOT_FOUND404Uno o más roles no encontrados, verifica los nombres.
7612PERMISSIONS_NOT_FOUND404Uno o más permisos no encontrados, verifica los nombres.
7613ROLE_PERMISSIONS_NOT_FOUND404Permisos del rol no encontrados, contacta a soporte.
7614CLIENT_ROLE_NOT_FOUND404Rol del cliente no encontrado, contacta a soporte.
7615CLIENT_ROLE_FORBIDDEN403No tienes permiso para acceder a este recurso.
7616KEYS_EXPIRED400Las llaves han expirado, rótalas.
7617ERROR_UPDATING_ROLE500Error al actualizar el rol, contacta a soporte.
7618INVALID_SIGNATURE_KEYS400Las llaves de firma son inválidas, rota las llaves e inicia sesión de nuevo.
7619ERROR_UPLOADING_FILE500Error al subir el archivo, inténtalo más tarde.
7620INVALID_FILE_TYPE500Tipo de archivo inválido, sube un archivo válido.
7621NO_SOCIALS_PROVIDED400No se proporcionaron enlaces de redes sociales, proporciona al menos uno.
7622INVALID_SOCIAL_URL400URL de red social inválida, verifica el formato de la URL.
7623ERROR_UPLOADING_SOCIALS400Error al subir los enlaces de redes sociales, inténtalo más tarde.
7624ERROR_SAVING_SOCIALS500Error al guardar los enlaces de redes sociales, inténtalo más tarde.
7625ERROR_FETCHING_COMMERCE_DOCS500Error al obtener los documentos del comercio, inténtalo más tarde.
7626MONTH_INVALID400El mes es inválido. Debe ser un valor entre 01 y 12.
7627YEAR_INVALID400El año es inválido. Debe ser un año válido.
7628FILE_SIZE_LIMIT_EXCEEDED400El tamaño del archivo excede el límite máximo permitido de 16 MB.
7629INVALID_EXCEL_FILE_TYPE400Tipo de archivo inválido. Solo se permiten archivos Excel (.xlsx, .xls).
7630FILE_IS_EMPTY400El archivo no puede estar vacío

Configuración de proyecto e integridad de la app (7700–7799)​

CódigoNombreHTTPMensaje
7700PROJECT_CONFIG_NOT_FOUND404Configuración del proyecto no encontrada
7701FORMS_NOT_FOUND500Formularios del proyecto no encontrados
7702FORM_DETAIL_NOT_FOUND404Detalles del formulario no encontrados
7703ERROR_UPDATING_PROJECT_CONFIG500Error al actualizar la configuración del proyecto, contacta a soporte.
7704ERROR_CREATING_PROJECT_CONFIG500Error al crear la configuración del proyecto, contacta a soporte.
7705MERCHANT_ALREADY_LINKED409El comercio ya está vinculado, obtén un nuevo comercio o verifícalo.
7706APP_INTEGRITY_VALIDATION_FAILED403Versión de la app no reconocida.
7707DEVICE_INTEGRITY_VALIDATION_FAILED403Estado de integridad del dispositivo no reconocido.
7708LICENSING_INTEGRITY_VALIDATION_FAILED403Estado de licenciamiento no reconocido.
7709INTEGRITY_TOKEN_EXPIRED_OR_INVALID401El token de integridad ha expirado o es inválido.
7710INTEGRITY_INVALID_HASH400El hash de integridad es inválido.
7711INTEGRITY_INVALID_APPLICATION_ID400El ID de aplicación de integridad es inválido.
7712APP_CONFIG_INTEGRITY_NOT_FOUND404Configuración de integridad de la app no encontrada.
7713COMMERCE_WEBHOOK_NOT_FOUND404El webhook no existe en ese comercio. Ver Webhooks de cobros.
7714COMMERCE_WEBHOOK_LIMIT_REACHED409El comercio alcanzó el máximo de webhooks (5).
7715COMMERCE_WEBHOOK_INVALID_URL400La URL del webhook debe ser una URL HTTPS pública en el puerto 443.
7716COMMERCE_WEBHOOK_INVALID_HEADERS400Los headers del webhook no son válidos.
7717COMMERCE_WEBHOOK_DUPLICATE_URL409El comercio ya tiene un webhook con esa URL.

App (8000–8099)​

CódigoNombreHTTPMensaje
8000APP_ERROR_CREDENTIALS401Credenciales inválidas, inténtalo de nuevo.
8001APP_NEED_CHANGE_PASSWORD401Primero debes cambiar tu contraseña.
8002APP_INVALID_ACCESS_TOKEN401Token de acceso inválido, inténtalo de nuevo.
8003APP_INVALID_REFRESH_TOKEN401Refresh token inválido, inténtalo de nuevo.
8004APP_INVALID_OTP401OTP inválido, inténtalo de nuevo.
8005APP_EMAIL_ALREADY_EXISTS409El correo ya existe, intenta con otro correo.
8006APP_USER_NOT_FOUND404Usuario no encontrado, verifica el id
8007APP_PARTNER_NOT_FOUND404Partner no encontrado, verifica el id
8008APP_PERMISSIONS_NOT_FOUND404Permisos asignados no encontrados, asigna permisos para este usuario.
8009APP_ERROR_USERS_FETCH500Parámetros de consulta inválidos o ID de partner no encontrado
8010APP_STATUS_INVALID400Estado de usuario inválido
8011APP_USER_SUSPENDED403Usuario suspendido
8012APP_USER_NOT_CREATED400Usuario no creado, inténtalo de nuevo.
8013APP_ERROR_CREATING_PERMISSIONS500Permiso no creado, inténtalo de nuevo.
8014APP_ERROR_GETTING_PERMISSIONS500Error al obtener los permisos, inténtalo de nuevo.
8015APP_ERROR_ASSIGN_PERMISSIONS500Error al intentar asignar permisos al usuario.
8016APP_PERMISSIONS_ALREADY_ASSIGNED409Uno o más permisos ya fueron asignados por este usuario para el partnerId
8017APP_ERROR_FINDING_ASSIGNED_PERMISSIONS500Error al buscar los permisos asignados a este usuario
8018APP_USER_INACTIVE403El usuario está inactivo
8019APP_USER_BLOCKED403Usuario bloqueado
8020APP_INVALID_OTP_PURPOSE500Propósito de OTP inválido.
8021APP_OTP_REQUIRED400El OTP es obligatorio.
8022APP_TOKEN_INVALID401El token es inválido.
8023APP_CARDHOLDER_NOT_FOUND404Tarjetahabiente no encontrado, verifica la información
8024APP_TEMPORARY_PASSWORD_EXPIRED409La contraseña temporal del usuario ha expirado; solicita una nueva a soporte.
8025APP_PROCESS_NOT_CREATED409Proceso no creado
8026APP_PROCESS_NOT_FOUND404Proceso no encontrado
8027APP_PROCESS_NOT_UPDATED409Proceso no actualizado
8028APP_ERROR_PROCESS500Error al procesar la solicitud
8029APP_CLIENT_BALANCE_NOT_FOUND404Balance del cliente no encontrado
8030APP_CLIENT_BALANCE_ALREADY_EXISTS409El balance del cliente ya existe
8031APP_CLIENT_BALANCE_NOT_UPDATED500Balance del cliente no actualizado
8032APP_ERROR_CLIENT_BALANCE500Error en el balance del cliente
8033APP_INSUFFICIENT_FUNDS_IN_CLIENT_ACCOUNT409Fondos insuficientes en la cuenta del cliente
8034APP_PROCESS_NOT_PENDING500El proceso no está pendiente
8035APP_PROCESS_NOT_APPROVED500El proceso no está aprobado
8036APP_PROCESS_NOT_REJECTED500El proceso no está rechazado

Notas​

  • El identificador estable es el nombre del error (la clave MigoNameErrors, p. ej. CARD_NOT_FOUND). Cada nombre mapea a un code numérico fijo. Ramifica tu lógica de cliente con code, pero trata el nombre como la clave canónica del registro.
  • Los códigos son strings, no enteros — compáralos como strings ("7200", no 7200).
  • Se agregan códigos nuevos con el tiempo. Trata los códigos desconocidos como errores genéricos y reintenta solo cuando el status HTTP sea reintentable (p. ej. 503/504).
  • Algunos códigos no tienen mensaje registrado en MigoErrorMessages; para esos la API usa el fallback 7003 (CONSULT_WITH_SUPPORT, "Please contact support for assistance.").

Migo usa dos espacios distintos de códigos de error de negocio según la API que estés llamando. El Wallet Gateway expone un code string dentro del array errors[] del envelope CustomResponse (los rangos 7000–8099 documentados arriba); el Middleware usa un envelope separado (ErrorResponseDto) con su propio code, anidado bajo error.code. Los rangos numéricos no se traslapan y la ruta del campo difiere.

El campo se llama code, no ownCode

El envelope de error del Middleware anida el código de negocio en error.code (string). Verificado contra el handler real: construye el objeto de error con getMigoErrorByOwnCode(), que devuelve { code, name, description } — no existe un campo ownCode en la respuesta.

El Middleware (links de pago, tokenización, pagos) expone el error de negocio en el campo code (anidado bajo error.code) en vez de errors[].code. Su forma es:

interface ErrorResponseDto {
message?: string;
error?: {
code?: string; // código de error de negocio de Migo (string, p. ej. "2002")
name?: string; // nombre corto del error (p. ej. "INVALID_TRX_ID")
description?: string; // descripción legible
};
}

Los códigos son strings numéricos cortos (p. ej. "2002") y no se solapan con el rango 7000–8099 anterior porque viven en un envelope y ruta de campo diferentes (error.code anidado, no errors[].code en un array).

Cuando envuelvas llamadas a ambas superficies en el mismo cliente, ramifica por ruta de campo:

const code = response?.errors?.[0]?.code ?? response?.error?.code;

Ciclo de vida de la transacción (2000–2099)​

Estos provienen de las operaciones de creación y consulta de la superficie de transacciones del Middleware — POST /transactions (crear) y GET /transactions (consultar).

HTTPcodeCausaQué hacer
4042000Transacción no encontrada para el uid indicado (GET /transactions?uid=)Verifica el identificador; la transacción pudo expirar o pertenecer a otro client.
4002002Error genérico de creaciónReintenta; si persiste, contacta a soporte con el payload de la solicitud y cualquier uid devuelto.
4092003amount está fuera de clientConfig.createTransactionRangeAmount, o un valor en processorAmount excede amountAjusta amount para que quede dentro del rango configurado; asegúrate de que cada valor de processorAmount sea <= amount.
4002004El cliente final (userId) está bloqueado para este clientLos usuarios bloqueados no pueden transaccionar — desbloquéalo a través de Migo antes de reintentar.
4002005El cliente final está suspendido para este clientEspera a que la suspensión expire o solicita a Migo quitarla.
4002006El cliente final está excluido para este clientLos usuarios excluidos no pueden transaccionar para este client en absoluto.
4012007Credenciales inválidas en el endpoint de hook (POST /transactions-hook) — el par privateKey/publicKey del body no corresponde a una aplicación registradaEste código no aplica a POST /transactions (que se autentica con bearer token vía el authorizer del gateway, no con privateKey/publicKey). Verifica las credenciales del hook con tu contacto de Migo.

Descarte / cancelación (4000–4099)​

Se devuelven por el endpoint de descarte de Pagos Alternativos — POST /api/v1/integrations/transactions/{transactionId}/dismiss. Consulta Descartar transacción para la matriz de estados elegibles.

HTTPcodeCausaQué hacer
4094020El estado de la transacción no es elegible para descartar (APPROVED, DENIED, EXPIRED, DISMISSED)Relee el estado de la transacción antes de descartar; solo CREATED, USED e IN_PROGRESS son elegibles.
4054021El procesador no permite descartar (sin hook de cancel) para una transacción en IN_PROGRESSNo todos los rieles soportan cancelación; deja que la transacción expire por sí sola.

Validación / configuración (5000–5099)​

Estos se devuelven cuando el body de la solicitud está mal formado o referencia algo que no existe en la configuración de Migo.

HTTPcodeCausaQué hacer
4095000Campos requeridos faltantes o forma del body inválidaVerifica que amount, userId, channel, client estén presentes con los tipos correctos.
4095004Slug de client no encontrado en la configuración de MigoConfirma la escritura del slug. Si el client debería existir, pide a Migo crearlo o activarlo.

Leer el código de error de forma defensiva​

type MiddlewareError = {
message?: string;
error?: {
code?: string; // código de error de negocio de Migo (string)
name?: string;
description?: string;
};
};

const code = err?.error?.code; // Middleware (anidado, string)
const fallback = err?.errors?.[0]?.code; // Gateway (string)

switch (String(code ?? fallback)) {
case '2007': return 'Invalid Migo credentials';
case '2003': return 'Amount out of allowed range';
case '5004': return 'Unknown client slug';
case '7200': return 'Card not found';
// ...
}

Semántica de reintentos​

Clase de error¿Reintentar?Estrategia
Network timeoutSíExponential backoff
500 / 502 / 504SíExponential backoff, máximo 3 reintentos
503SíExponential backoff con techo amplio (hasta 5 min)
400 / 422NoCorrige la solicitud
401No (refresca en su lugar)Refresca el token, luego reintenta
403 / 404 / 409NoNo reintentes

Patrón cliente​

async function call<T>(fn: () => Promise<T>, attempt = 0): Promise<T> {
try {
return await fn();
} catch (err) {
const status = err.response?.status;
if (status === 401) {
await refreshToken();
return call(fn, attempt + 1);
}
if ([500, 502, 503, 504].includes(status) && attempt < 3) {
const wait = 2 ** attempt * 500;
await new Promise(r => setTimeout(r, wait));
return call(fn, attempt + 1);
}
throw err;
}
}

Reportar incidentes​

Al abrir un ticket de soporte incluye:

  • El timestamp de la solicitud en UTC (Migo lo correlaciona con la traza interna)
  • URL completa de la solicitud, método y headers (oculta el Bearer token)
  • Body de la solicitud (oculta PANs y CVVs)
  • Body completo de la respuesta