Cómo gestionar los mensajes de error de códigos QR en C
La gestión de errores de IronQR te ayuda a detectar fallos de lectura y escritura, registrar diagnósticos y obtener resultados claros en cada escaneo. En España, un error silencioso en la generación del QR de AEAT puede traducirse en una factura no conforme con VERI*FACTU (Real Decreto 1007/2023) o en un ticket TicketBAI rechazado por las haciendas forales de Bizkaia, Gipuzkoa y Araba. Si no se añaden comprobaciones explícitas, tanto un resultado vacío como un archivo dañado no devolverán nada, por lo que no sabrás qué ha fallado. Al añadir un manejo de excepciones específico y un registro de diagnóstico, puede convertir los fallos silenciosos en información útil. Esta guía explica cómo gestionar los resultados vacíos, gestionar las excepciones en tiempo de escritura y crear un envoltorio de registro estructurado para el procesamiento por lotes.
Guía de inicio rápido: Gestionar errores de códigos QR
Envuelva las operaciones de lectura de QR en un bloque try-catch y registre diagnósticos para fallos de archivo y decodificación.
-
Instala IronQR con el Administrador de Paquetes NuGet
PM > Install-Package IronQR -
Copie y ejecute este fragmento de código.
using IronQr; using IronSoftware.Drawing; try { var input = new QrImageInput(AnyBitmap.FromFile("label.png")); var results = new QrReader().Read(input); Console.WriteLine($"Found {results.Count()} QR code(s)"); } catch (IOException ex) { Console.Error.WriteLine($"File error: {ex.Message}"); } -
Despliegue para probar en su entorno real
Comienza a usar IronQR en tu proyecto hoy mismo con una prueba gratuita
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca IronQR C# para la gestión de errores de códigos QR
- Envuelva las llamadas de lectura/escritura de QR en bloques
try-catch - Captura
IOExceptionyArgumentExceptionpara errores específicos - Registrar diagnósticos de resultados vacíos y excepciones
- Utilice el registro JSON estructurado para la observabilidad del pipeline
Gestión de errores de lectura y resultados vacíos
Sin registro, un resultado vacío y un archivo dañado parecen idénticos para el usuario. El siguiente ejemplo detecta errores de acceso a archivos y emite una advertencia si el análisis no devuelve ningún resultado.
Entrada
Este ejemplo de entrada QR se encuentra en el disco. Simularemos ambos escenarios: uno en el que el usuario recupera y descodifica el archivo, y otro en el que la ruta del archivo es incorrecta.
:path=/static-assets/qr/content-code-examples/how-to/detailed-error-messages/read-diagnostics.cs
using IronQr;
using IronSoftware.Drawing;
string filePath = "damaged-scan.png";
try
{
// File-level failure throws IOException or FileNotFoundException
var inputBmp = AnyBitmap.FromFile(filePath);
var imageInput = new QrImageInput(inputBmp);
var reader = new QrReader();
IEnumerable<QrResult> results = reader.Read(imageInput);
if (!results.Any())
{
// Not an exception — but a diagnostic event worth logging
Console.Error.WriteLine($"[WARN] No QR codes found in: {filePath}");
Console.Error.WriteLine($" Action: Verify image quality or try a different scan");
}
else
{
foreach (QrResult result in results)
{
Console.WriteLine($"[{result.QrType}] {result.Value}");
}
}
}
catch (FileNotFoundException)
{
Console.Error.WriteLine($"[ERROR] File not found: {filePath}");
}
catch (IOException ex)
{
Console.Error.WriteLine($"[ERROR] Cannot read file: {filePath} — {ex.Message}");
}
catch (Exception ex)
{
Console.Error.WriteLine($"[ERROR] Unexpected failure reading {filePath}: {ex.GetType().Name} — {ex.Message}");
}
Imports IronQr
Imports IronSoftware.Drawing
Module Module1
Sub Main()
Dim filePath As String = "damaged-scan.png"
Try
' File-level failure throws IOException or FileNotFoundException
Dim inputBmp = AnyBitmap.FromFile(filePath)
Dim imageInput = New QrImageInput(inputBmp)
Dim reader = New QrReader()
Dim results As IEnumerable(Of QrResult) = reader.Read(imageInput)
If Not results.Any() Then
' Not an exception — but a diagnostic event worth logging
Console.Error.WriteLine($"[WARN] No QR codes found in: {filePath}")
Console.Error.WriteLine(" Action: Verify image quality or try a different scan")
Else
For Each result As QrResult In results
Console.WriteLine($"[{result.QrType}] {result.Value}")
Next
End If
Catch ex As FileNotFoundException
Console.Error.WriteLine($"[ERROR] File not found: {filePath}")
Catch ex As IOException
Console.Error.WriteLine($"[ERROR] Cannot read file: {filePath} — {ex.Message}")
Catch ex As Exception
Console.Error.WriteLine($"[ERROR] Unexpected failure reading {filePath}: {ex.GetType().Name} — {ex.Message}")
End Try
End Sub
End Module
Resultado
La consola a continuación muestra un [WARN] para el caso de resultado vacío y un [ERROR] para el archivo faltante, con la ruta de archivo y una acción sugerida para cada uno.
Gestión de errores de escritura
Pasar null a QrWriter.Write activa un IronQrEncodingException. Los datos que superen la capacidad del nivel de corrección de errores configurado también se descartan, ya que los niveles de corrección más altos reducen la capacidad de datos disponible.
Entrada
Las dos variables de entrada a continuación definen los escenarios de fallo: nullContent es null y oversizedContent es una cadena de 5,000 caracteres que excede la capacidad del QR en el nivel de corrección más alto.
:path=/static-assets/qr/content-code-examples/how-to/detailed-error-messages/write-diagnostics.cs
using IronQr;
string? content = null; // null throws IronQrEncodingException
string oversizedContent = new string('A', 5000); // 5,000 chars exceeds QR capacity at Highest error correction level
// Scenario 1: null input
try
{
QrCode qr = QrWriter.Write(content); // Input
}
catch (Exception ex)
{
Console.Error.WriteLine($"[ERROR] Null content: {ex.GetType().Name} — {ex.Message}"); // Output
}
// Scenario 2: data exceeds QR capacity at the configured error correction level
try
{
var options = new QrOptions(QrErrorCorrectionLevel.Highest);
QrCode qr = QrWriter.Write(oversizedContent, options); // Input
}
catch (Exception ex)
{
Console.Error.WriteLine($"[ERROR] QR capacity exceeded: {ex.Message}"); // Output
Console.Error.WriteLine($" Input length: {oversizedContent.Length} chars");
Console.Error.WriteLine($" Action: Reduce content or lower error correction level");
}
Imports IronQr
Dim content As String = Nothing ' Nothing throws IronQrEncodingException
Dim oversizedContent As String = New String("A"c, 5000) ' 5,000 chars exceeds QR capacity at Highest error correction level
' Scenario 1: null input
Try
Dim qr As QrCode = QrWriter.Write(content) ' Input
Catch ex As Exception
Console.Error.WriteLine($"[ERROR] Null content: {ex.GetType().Name} — {ex.Message}") ' Output
End Try
' Scenario 2: data exceeds QR capacity at the configured error correction level
Try
Dim options As New QrOptions(QrErrorCorrectionLevel.Highest)
Dim qr As QrCode = QrWriter.Write(oversizedContent, options) ' Input
Catch ex As Exception
Console.Error.WriteLine($"[ERROR] QR capacity exceeded: {ex.Message}") ' Output
Console.Error.WriteLine($" Input length: {oversizedContent.Length} chars")
Console.Error.WriteLine(" Action: Reduce content or lower error correction level")
End Try
Resultado
La consola muestra el tipo de excepción y el mensaje para ambos casos de fallo.
Registre la longitud de la entrada junto con el mensaje de excepción para determinar si el problema requiere un contenido más breve o un nivel de corrección más bajo. En cuanto a las entradas del usuario, valide la longitud de las cadenas y compruebe si hay valores nulos antes de la codificación para reducir la sobrecarga de excepciones y mejorar el diagnóstico.
Registro de operaciones de códigos QR
Utilice IronSoftware.Logger para capturar diagnósticos internos. Para cada operación de lectura, implemente un ayudante que registre la ruta del archivo, el recuento de resultados y el tiempo transcurrido en formato JSON para garantizar una salida clara de todo el lote.
Entrada
El lote incluye cuatro imágenes de códigos QR válidas de qr-scans/ y un quinto archivo, scan-05-broken.png, con bytes no válidos.
Escaneo 1
Escanear 2
Escaneo 3
Escanear 4
:path=/static-assets/qr/content-code-examples/how-to/detailed-error-messages/logging-wrapper.cs
using IronQr;
using IronSoftware.Drawing;
using System.Diagnostics;
// Enable shared Iron Software logging for internal diagnostics
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All;
IronSoftware.Logger.LogFilePath = "ironqr-debug.log";
// Reusable wrapper for structured observability
(IEnumerable<QrResult> Results, bool Success, string Error) ReadQrWithDiagnostics(string filePath)
{
var sw = Stopwatch.StartNew();
try
{
var input = new QrImageInput(AnyBitmap.FromFile(filePath));
var results = new QrReader().Read(input).ToList();
sw.Stop();
Console.WriteLine($"{{\"op\":\"qr_read\",\"file\":\"{Path.GetFileName(filePath)}\","
+ $"\"status\":\"ok\",\"count\":{results.Count},\"ms\":{sw.ElapsedMilliseconds}}}");
return (results, true, null);
}
catch (Exception ex)
{
sw.Stop();
string error = $"{ex.GetType().Name}: {ex.Message}";
Console.Error.WriteLine($"{{\"op\":\"qr_read\",\"file\":\"{Path.GetFileName(filePath)}\","
+ $"\"status\":\"error\",\"exception\":\"{ex.GetType().Name}\","
+ $"\"message\":\"{ex.Message}\",\"ms\":{sw.ElapsedMilliseconds}}}");
return (Enumerable.Empty<QrResult>(), false, error);
}
}
// Usage: process a batch with per-file isolation
string[] files = Directory.GetFiles("qr-scans/", "*.png");
int ok = 0, fail = 0;
foreach (string file in files)
{
var (results, success, error) = ReadQrWithDiagnostics(file);
if (success && results.Any()) ok++;
else fail++;
}
Console.WriteLine($"\nBatch complete: {ok} success, {fail} failed/empty out of {files.Length} files");
Imports IronQr
Imports IronSoftware.Drawing
Imports System.Diagnostics
Imports System.IO
Imports System.Linq
' Enable shared Iron Software logging for internal diagnostics
IronSoftware.Logger.LoggingMode = IronSoftware.Logger.LoggingModes.All
IronSoftware.Logger.LogFilePath = "ironqr-debug.log"
' Reusable wrapper for structured observability
Private Function ReadQrWithDiagnostics(ByVal filePath As String) As (IEnumerable(Of QrResult), Boolean, String)
Dim sw = Stopwatch.StartNew()
Try
Dim input = New QrImageInput(AnyBitmap.FromFile(filePath))
Dim results = New QrReader().Read(input).ToList()
sw.Stop()
Console.WriteLine($"{{""op"":""qr_read"",""file"":""{Path.GetFileName(filePath)}"",""status"":""ok"",""count"":{results.Count},""ms"":{sw.ElapsedMilliseconds}}}")
Return (results, True, Nothing)
Catch ex As Exception
sw.Stop()
Dim error As String = $"{ex.GetType().Name}: {ex.Message}"
Console.Error.WriteLine($"{{""op"":""qr_read"",""file"":""{Path.GetFileName(filePath)}"",""status"":""error"",""exception"":""{ex.GetType().Name}"",""message"":""{ex.Message}"",""ms"":{sw.ElapsedMilliseconds}}}")
Return (Enumerable.Empty(Of QrResult)(), False, error)
End Try
End Function
' Usage: process a batch with per-file isolation
Dim files As String() = Directory.GetFiles("qr-scans/", "*.png")
Dim ok As Integer = 0, fail As Integer = 0
For Each file As String In files
Dim result = ReadQrWithDiagnostics(file)
Dim results = result.Item1
Dim success = result.Item2
Dim error = result.Item3
If success AndAlso results.Any() Then
ok += 1
Else
fail += 1
End If
Next
Console.WriteLine($"\nBatch complete: {ok} success, {fail} failed/empty out of {files.Length} files")
Resultado
La consola muestra líneas de registro JSON para cada archivo: cuatro lecturas correctas y una entrada de error estructurada para el archivo dañado, seguidas del resumen del lote. IronSoftware.Logger escribe diagnósticos internos en IronQR-debug.log al mismo tiempo. Puede descargar el registro de depuración completo aquí.
La salida JSON se alimenta directamente en herramientas de agregación de registros: canalice stdout a Fluentd, Datadog o CloudWatch en un despliegue en contenedores. El campo ms muestra regresiones de latencia, y el registro de depuración captura pasos de procesamiento internos que el envoltorio no captura.
Más información
- Niveles de corrección de errores: ajusta la resistencia del QR a nivel de codificación.
- Guía práctica para leer códigos QR: tutorial paso a paso de la lectura.
- Tutorial del generador de códigos QR: generación con estilos y logotipos.
- Referencia de la API de QrReader: firmas de métodos y comentarios.
- Referencia API de QrWriter: todas las sobrecargas de
Write.
Consulte las opciones de licencia cuando esté listo para la producción.
Haga clic aquí para descargar el proyecto completo de la aplicación de consola DetailedErrorMessagesTest.
Aplicaciones regulatorias en España
En el mercado español, los errores en la codificación de códigos QR tienen consecuencias directas sobre el cumplimiento fiscal y regulatorio. Una gestión de errores robusta con IronQR no es una práctica opcional: es la diferencia entre una factura válida ante la AEAT y una infracción tributaria.
*Errores en QR de AEAT / VERIFACTU.* El reglamento VERIFACTU (Real Decreto 1007/2023) especifica con precisión el formato de la URL de verificación que debe codificar cada código QR de factura: https://sede.agenciatributaria.gob.es/Sede/facturae/verificar?nif={nif}&numserie={serie}&fecha={fecha}&importe={total}. Un error de codificación —longitud de datos excesiva, carácter no válido en el NIF, o formato de fecha incorrecto— produce un QR inescaneble que la AEAT rechazará durante la verificación. Capturar IronQrEncodingException y registrar la longitud del payload junto con el mensaje de error permite al equipo de desarrollo diagnosticar y corregir estos problemas antes de que lleguen a producción.
Errores en QR TicketBAI. Las especificaciones técnicas de las haciendas forales de Bizkaia, Gipuzkoa y Araba establecen requisitos estrictos sobre el contenido del QR TicketBAI: el código TicketBAI, el NIF proveedor, el importe total y la fecha emisión deben codificarse en un formato exacto. Un resultado vacío de QrReader.Read sobre un ticket impreso puede indicar un QR mal generado por el software del proveedor o un problema de contraste en la impresión. El patrón [WARN] / [ERROR] descrito en esta guía es la base de un sistema de alertas de calidad en los TPV vascos.
Validación de DataMatrix SEVeM y SILICIE. La AEMPS exige que el DataMatrix de cada medicamento codifique correctamente los campos de trazabilidad (GTIN, número de lote, fecha de caducidad, número de serie). Un ArgumentNullException por contenido nulo o un ArgumentException por exceso de capacidad son señales de un defecto en el pipeline de generación de etiquetas. Del mismo modo, la AEAT gestiona el sistema SILICIE para el control de contadores de alcohol, donde un DataMatrix mal codificado puede invalidar un movimiento de mercancía ante la administración.
Ejemplo práctico: diagnóstico de un error de QR AEAT en un sistema VeriFactu
Imagine un sistema de facturación electrónica que debe generar el QR de AEAT para cada factura emitida bajo VERI*FACTU. Durante las pruebas de integración, el equipo detecta que un lote de 200 facturas produce resultados vacíos al escanear los QR generados. El flujo de diagnóstico con IronQR es el siguiente:
- Se habilita
IronSoftware.LoggerconLoggingMode = Allpara capturar el detalle interno de cada operación. - El envoltorio de registro estructurado registra, para cada factura, la URL codificada, la longitud del payload y el tiempo de codificación.
- El análisis del log revela que las facturas con
importe totalsuperior a 9.999,99 € producen un payload de 156 caracteres, superando la capacidad del nivel de corrección H configurado. - La solución: reducir el nivel de corrección a M (
ErrorCorrectionLevel.Medium) para payloads de más de 130 caracteres, o truncar el importe a dos decimales antes de la codificación. - Tras el fix, el procesamiento por lotes de 200 facturas produce cuatro lecturas correctas y un único
[ERROR]estructurado —la factura con NIF malformado— que el sistema de alertas escala automáticamente al equipo de soporte.
Este patrón garantiza que ninguna factura VeriFactu llegue al cliente con un QR inválido, evitando sanciones por incumplimiento del Real Decreto 1007/2023.
Diagnostique y corrija errores de QR en sistemas VeriFactu, TicketBAI y SEVeM con IronQR en C#.
Preguntas Frecuentes
¿Cómo puedo diagnosticar un error en el QR de AEAT generado por mi sistema VeriFactu?
Active IronSoftware.Logger con LoggingMode = All antes de la operación de codificación. Capture IronQrEncodingException y registre la longitud del payload de la URL de verificación de la AEAT. Si la URL supera la capacidad del nivel de corrección configurado, reduzca el nivel a ErrorCorrectionLevel.Medium o verifique que el NIF y el importe tengan el formato correcto según la especificación VERI*FACTU.
¿Qué errores son más habituales en los QR TicketBAI de Bizkaia, Gipuzkoa y Araba?
Los errores más frecuentes en QR TicketBAI son: fecha de emisión en formato incorrecto (debe ser AAAA-MM-DD según las especificaciones forales), NIF proveedor con caracteres no permitidos, y payload que supera la capacidad del nivel de corrección H. IronQR reporta estos casos como IronQrEncodingException con el mensaje de error exacto, facilitando la corrección.
¿Cómo puedo depurar operaciones de lectura/escritura de códigos QR en C#?
Puede depurar operaciones de lectura/escritura de códigos QR en C# usando IronQR capturando excepciones, registrando diagnósticos y monitoreando el procesamiento por lotes con salida estructurada.
¿Cómo ayuda IronQR a monitorear el procesamiento por lotes de códigos QR?
IronQR ayuda a monitorear el procesamiento por lotes de códigos QR proporcionando salida estructurada en JSON, lo cual ayuda a identificar y solucionar cualquier error o ineficiencia durante el proceso, incluyendo facturas con QR inválido para AEAT o TicketBAI.
¿Puede IronQR registrar diagnósticos para operaciones de códigos QR?
Sí, IronQR puede registrar diagnósticos para operaciones de códigos QR mediante IronSoftware.Logger, permitiéndole rastrear y analizar errores en sus sistemas de facturación VeriFactu, SII o TicketBAI en C#.
¿Cuáles son las excepciones comunes en el procesamiento de códigos QR con IronQR?
Las excepciones más comunes son IronQrEncodingException por contenido nulo o exceso de capacidad, IOException por errores de archivo, y resultados vacíos cuando el QR escaneado es ilegible. En sistemas de facturación AEAT, el exceso de capacidad por importes altos o URLs largas es la causa más frecuente.

