Códigos de error y de resultado

Toda respuesta de error de la API es un Problem Details (RFC 9457) con una propiedad adicional, codigo, que no cambia entre versiones. Decide siempre por codigo, nunca por el texto: detail es para ti, no para mostrarlo al cliente.

{
  "type": "urn:finora:pos:checkout:sesion-vencida",
  "title": "Sesión vencida",
  "status": 410,
  "detail": "La sesión venció al intentar usarla",
  "codigo": "SESION_VENCIDA"
}

Con la clave API (tu servidor)

codigo	HTTP	Cuándo	Qué hacer
CLAVE_INVALIDA	401	La clave falta, es incorrecta o fue revocada	Revisa la configuración; pide una clave nueva si la revocaron
CLAVE_SIN_ACCESO_AL_COMERCIO	403	La clave no alcanza el comercio indicado	Usa la clave de ese comercio o de su principal
CLAVE_COMERCIO_SUSPENDIDO	403	El comercio está suspendido o cerrado: no se abren sesiones	Contacta a tu adquirente
TERMINAL_AJENO	403	El terminal no es de tu comercio	Corrige el terminalId
PETICION_INVALIDA	400	Monto cero o negativo, moneda inválida, tiempo de vida fuera de 60 a 3600, URL que no es http(s), JSON ilegible	Corrige lo que indica detail
SESION_NO_ENCONTRADA	404	La sesión no existe o no es de tu comercio	Revisa el sesionId guardado
TERMINAL_NO_ENCONTRADO, COMERCIO_NO_ENCONTRADO, ENTREGA_NO_ENCONTRADA	404	El recurso no existe	Revisa el identificador
COBRO_EN_CURSO	409	Cancelas con una autorización en vuelo o con el terminal ya leyendo la tarjeta	Espera el veredicto

Con el token de cliente (navegador)

El componente ya maneja estos casos. La columna de la derecha dice qué hace, por si construyes tu propia interfaz.

codigo	HTTP	Cuándo	Qué hace el componente
TOKEN_INVALIDO	401	Token ausente, inválido, de otra sesión, o sesión inexistente	Pantalla de error final y evento finora-error
SESION_VENCIDA	410	La sesión venció al usarla	Resultado EXPIRADA
SESION_CERRADA	409	La sesión ya tiene veredicto, se canceló o venció	Consulta el estado y muestra lo que diga el servidor
COBRO_EN_CURSO	409	Ya hay un cobro en vuelo	Pasa a esperar el veredicto
MEDIO_NO_DISPONIBLE	400	Medio inactivo, fuera de los límites, efectivo, o tarjeta sin terminal	Vuelve a los medios con el aviso
DATOS_INCOMPLETOS	400	Faltan campos o no tienen el formato. detail nombra cada campo entre comillas simples	Marca cada campo citado y enfoca el primero
PETICION_INVALIDA	400	JSON ilegible o medio ausente	Aviso y vuelve atrás
TERMINAL_OCUPADO	409	El terminal tiene otra orden en curso	Vuelve a los medios: «El terminal está ocupado»
TERMINAL_NO_ENCONTRADO, TERMINAL_AJENO	404, 403	El terminal no existe o no es del comercio	Vuelve a los medios y sugiere pedir ayuda al personal
COMERCIO_SUSPENDIDO	403	El comercio se suspendió después de abrir la sesión	Muestra «comercio suspendido» y no ofrece medios
DEMASIADAS_PETICIONES	429	Más de 60 peticiones por minuto sobre la sesión (Retry-After: 60)	Aviso; la consulta de estado sigue a su ritmo
RED	—	El navegador no pudo conectar	Al cargar, ofrece reintentar; durante la espera, sigue intentando

Códigos de la sesión

No son errores HTTP: vienen en codigo dentro del resultado.

codigo	Con estado	Significa
TERMINAL_SIN_RESPUESTA	CREADA	El terminal no tomó la orden a tiempo. El cliente puede elegir otro medio
CANCELADA_EN_TERMINAL	CREADA	El cajero canceló la orden en el terminal. El cliente puede elegir otro medio
CANCELADA_POR_CLIENTE, CANCELADA_POR_COMERCIO	CANCELADA	Quién retiró la sesión

Códigos de respuesta del banco

Son los códigos de respuesta ISO 8583 que devuelve el autorizador. Estos son los que verás en sandbox:

Código	Significado	Efecto en la sesión
00	Aprobada	APROBADA
51	Fondos insuficientes	Intento rechazado; el cliente puede reintentar
05	No honrar	Intento rechazado
61	Excede el límite	Intento rechazado
14	Teléfono, cuenta o billetera inválidos	Intento rechazado
57	Teléfono no afiliado a pago móvil	Intento rechazado
62	Cuenta o referencia no encontrada	Intento rechazado
43, 54, 41	Tarjeta retenida, vencida o extraviada (en el terminal)	Intento rechazado
96	El banco respondió tarde	EN_DUDA; en sandbox se resuelve aprobada
91	El banco no registró la operación	EN_DUDA; en sandbox se resuelve rechazada

Un intento rechazado deja la sesión abierta. La sesión termina RECHAZADA solo si el cliente o el comercio la cancelan después de uno o más rechazos, con el código del último.