Códigos de respuesta y errores

Hay dos familias de respuestas, y conviene no mezclarlas:

• Decisiones del emisor (HTTP 200): llevan resultado y codigoRespuesta (DE 39). Decides por resultado.
• Errores de protocolo (HTTP 4xx y 503): llegan como application/problem+json (RFC 9457) con un codigo estable. Ninguno llega al emisor, salvo NO_ENVIADA, que por definición no salió.

Catálogo del DE 39

DE 39	mensaje	resultado	¿Reintentar?
00	Aprobada	APROBADA	—
10	Aprobada parcialmente	APROBADA	— Solo con opciones.aprobacionParcial. Cobra monto.aprobado y pide el resto por otro medio
03	Comercio no válido	RECHAZADA	No. Revisa el registro del comercio con FINORA
05	No aprobada	RECHAZADA	No con los mismos datos
12	Transacción no válida	RECHAZADA	No. Revisa la operación
13	Importe no válido	RECHAZADA	No con el mismo importe
14	Tarjeta no válida	RECHAZADA	No
25	Operación original no encontrada	RECHAZADA	No. Aplica a reverso, captura y devolución
51	Fondos insuficientes	RECHAZADA	Solo como operación nueva (otra clave), si el titular lo decide
54	Tarjeta vencida	RECHAZADA	No
55	Credencial no válida	RECHAZADA	Solo con una credencial FPW1 nueva (otra clave)
57	Operación no permitida al titular	RECHAZADA	No
61	Excede el límite de importe	RECHAZADA	No con el mismo importe
62	Tarjeta restringida	RECHAZADA	No
65	Excede el límite de frecuencia	RECHAZADA	Más tarde, como operación nueva
91	Sin respuesta en el plazo; se envió el reverso	INDETERMINADA	No. El reverso ya está en curso; consulta con GET
—	El emisor no está disponible; no se envió nada	NO_ENVIADA (HTTP 503)	Sí, con la misma clave, tras Retry-After

Cualquier otro código del emisor se publica como RECHAZADA con el mensaje «No aprobada». Los códigos 91, 94 y 96 del emisor no deciden nada: el autorizador los trata como INDETERMINADA, reversa la operación y a ti siempre te muestra 91.

«Reintentar con la misma clave» devuelve la respuesta guardada; por eso, tras una RECHAZADA, un nuevo intento es siempre una operación nueva con otra Idempotency-Key.

Errores HTTP

Formato RFC 9457, con type = urn:finora:auth-gateway:<codigo-en-kebab> y traceId para soporte:

{
  "type": "urn:finora:auth-gateway:comercio-ajeno",
  "title": "Comercio no registrado para el cliente",
  "status": 403,
  "codigo": "COMERCIO_AJENO",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

HTTP	codigo	Significado	¿Reintentar?
400	ESQUEMA_INVALIDO	JSON inválido, propiedad desconocida o duplicada, tipo o patrón que no cumple, Idempotency-Key ausente o mal formada	No. Corrige la petición
400	MONTO_INVALIDO	Escala distinta de 2 decimales, cero o más de 10 enteros. Nunca se redondea	No. Corrige el importe
400	DE_NO_PERMITIDO, DE_INVALIDO_PARA_LAYOUT, ETIQUETA_DE48_NO_PERMITIDA	Vista ISO: DE prohibido o reservado, valor que no cabe en el formato del emisor, o etiqueta del DE 48 no admitida	No
401	FIRMA_INVALIDA, RELOJ_FUERA_DE_TOLERANCIA, NONCE_REPETIDO, CERTIFICADO_NO_REGISTRADO	Autenticación del canal	Sí, con firma, fecha y nonce nuevos
403	CLIENTE_SUSPENDIDO, IP_NO_PERMITIDA, OPERACION_NO_PERMITIDA, VISTA_ISO_NO_HABILITADA, COMERCIO_AJENO, MCC_NO_COINCIDE, MONEDA_NO_HABILITADA	Tu cliente no está autorizado para eso	No. Revisa tu registro con FINORA
404	AUTORIZACION_NO_ENCONTRADA	No existe o es de otro cliente	No
409	ORIGINAL_NO_ADMITE_OPERACION	La original no admite reverso, captura o devolución en su estado; detail dice por qué	Según el detail (ver Flujos)
422	IDEMPOTENCIA_CUERPO_DISTINTO	Misma clave con otro cuerpo; trae el idAutorizacion que ya la usa	No. Consulta esa autorización
422	MONTO_EXCEDE_ORIGINAL, MONEDA_DISTINTA_ORIGINAL	Captura o devolución por encima de lo aprobado o en otra moneda	No con ese importe
429	LIMITE_DE_TASA	Por encima de tu límite o del límite global	Sí, tras Retry-After
503	CANAL_NO_DISPONIBLE	El autorizador no puede verificar su registro o su base (falla cerrado)	Sí, con la misma clave

Los mensajes de los 401 son deliberadamente genéricos: no indican qué parte de la autenticación falló.