rustedf.cloud
Menú

Generar miles de PDF en C#: ritmo, 429 y reintentos seguros

Publicado el 3 min de lectura

Facturas de fin de mes, un certificado para cada asistente, un extracto para cada cliente: tarde o temprano necesitas miles de PDF, no uno. El código obvio, una lista de tareas y Task.WhenAll, envía todas las peticiones a la vez, y el servicio responde 429 a la mayoría. Esta guía arma un ejecutor de lotes que respeta la tasa de tu plan, repite lo que es seguro repetir y se puede parar y reanudar sin rehacer el mismo trabajo. Usa el estilo de cliente tipado de la guía de C# y ASP.NET Core.

Conoce primero los límites

  • La tasa de peticiones pertenece a la cuenta. Tu plan fija cuántas peticiones por minuto puede hacer la cuenta, y todas las claves la comparten. Una segunda clave no sube el límite; solo reparte la misma cuota. Los números están en la página de planes.
  • Un renderizado cuesta un crédito, y uno que falla no cuesta nada. Se toma un crédito cuando empieza el renderizado y se devuelve si falla, así que repetir un fallo es seguro.
  • Sin créditos llega un 402. No se renderizó nada, y cualquier otra petición fallaría igual, así que el lote entero debe parar.

Comprueba el saldo antes de empezar. GET /v1/me devuelve tu plan y tus créditos:

public sealed record Me(string Plan, long Credits);
var me = await http.GetFromJsonAsync<Me>("v1/me", cancellationToken);
if (me!.Credits < jobs.Count)
throw new InvalidOperationException($"{me.Credits} créditos para {jobs.Count} documentos.");

Controla el ritmo de las llamadas

Un token bucket deja pasar una petición cada cierto tiempo, sea cual sea el número de workers. .NET trae uno en System.Threading.RateLimiting:

using System.Threading.RateLimiting;
var limiter = new TokenBucketRateLimiter(new TokenBucketRateLimiterOptions
{
TokenLimit = 1,
TokensPerPeriod = 1,
ReplenishmentPeriod = TimeSpan.FromSeconds(60.0 / requestsPerMinute),
QueueLimit = int.MaxValue,
QueueProcessingOrder = QueueProcessingOrder.OldestFirst,
AutoReplenishment = true,
});

Fija requestsPerMinute algo por debajo de la tasa de tu plan, para que otras llamadas de la misma cuenta sigan cabiendo. Cada worker toma un token antes de enviar una petición.

El ejecutor

using System.Collections.Concurrent;
using System.Net;
using System.Net.Http.Json;
public sealed record Job(string Number, string TemplateId, string Locale, Dictionary<string, object?> Data);
public sealed class OutOfCreditsException : Exception;
public sealed class BatchRenderer(HttpClient http, TokenBucketRateLimiter limiter, int workers)
{
public async Task<IReadOnlyList<string>> RunAsync(
IEnumerable<Job> jobs, string folder, CancellationToken cancellationToken)
{
var failed = new ConcurrentBag<string>();
var options = new ParallelOptions
{
MaxDegreeOfParallelism = workers,
CancellationToken = cancellationToken,
};
await Parallel.ForEachAsync(jobs, options, async (job, token) =>
{
var path = Path.Combine(folder, $"{job.Number}.pdf");
if (File.Exists(path)) return; // hecho en una ejecución anterior
try
{
var pdf = await RenderAsync(job, token);
await File.WriteAllBytesAsync(path + ".part", pdf, token);
File.Move(path + ".part", path, overwrite: true);
}
catch (OutOfCreditsException) { throw; } // para el lote entero
catch (Exception) when (!token.IsCancellationRequested)
{
failed.Add(job.Number); // un documento malo no frena a los demás
}
});
return failed.ToArray();
}
}

Tres hábitos hay en ese código:

  • Escribe en un nombre temporal y luego muévelo. Una ejecución interrumpida a medias nunca deja medio archivo con aspecto de terminado.
  • Salta lo que ya existe. Lanza el mismo lote otra vez y solo hace los documentos que faltan, así que reanudar una ejecución parada no cuesta nada.
  • Guarda los fallos. El método devuelve los números que fallaron, para que los revises, corrijas los datos y ejecutes de nuevo.

Repite solo lo seguro

Este método pertenece a la clase BatchRenderer:

private async Task<byte[]> RenderAsync(Job job, CancellationToken cancellationToken)
{
for (var attempt = 1; ; attempt++)
{
using var lease = await limiter.AcquireAsync(1, cancellationToken);
using var response = await http.PostAsJsonAsync(
"v1/render",
new { template_id = job.TemplateId, data = job.Data, locale = job.Locale },
cancellationToken);
if (response.IsSuccessStatusCode)
return await response.Content.ReadAsByteArrayAsync(cancellationToken);
if (response.StatusCode == HttpStatusCode.PaymentRequired)
throw new OutOfCreditsException();
var retry = response.StatusCode is HttpStatusCode.TooManyRequests
or HttpStatusCode.ServiceUnavailable
|| (int)response.StatusCode >= 500;
if (!retry || attempt == 5)
throw new InvalidOperationException($"{job.Number}: {(int)response.StatusCode}");
var wait = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(Math.Pow(2, attempt));
await Task.Delay(wait + TimeSpan.FromMilliseconds(Random.Shared.Next(0, 500)), cancellationToken);
}
}
Estado Qué hace el ejecutor
200 Devuelve el PDF.
402 Para el lote entero: sin créditos, no se renderizó nada.
429, 503, 5xx Espera el Retry-After, o retrocede, y lo intenta de nuevo, hasta cinco veces. Un renderizado que falla no consume crédito.
Otros 4xx No repite. La petición es incorrecta; el documento se registra como fallo.

A cada espera se le suma un pequeño retraso aleatorio, para que los workers que se frenaron juntos no vuelvan en el mismo instante.

Un caso que evitar

Si el servicio termina un renderizado pero tu lado nunca recibe la respuesta, por ejemplo por un tiempo límite de red, y vuelves a enviar la petición, es un renderizado nuevo y cuesta otro crédito. Mantén el tiempo límite del HttpClient por encima del límite de tiempo de tu plan, para que un documento lento no se abandone demasiado pronto, y lee el X-Render-Id de cada respuesta en tu registro, para distinguir los documentos que se hicieron de los que no.

Mantén cada petición pequeña

Envía una plantilla guardada y solo los datos, como en esta guía, y no todo el HTML cada vez. El tamaño de una entrada lo limita tu plan; una petición demasiado grande responde 413. Consulta Generar con una plantilla guardada.

Lee Errores y límites y Generar un PDF. Para una versión de la misma idea basada en colas, consulta Generar un PDF en Azure Functions.

← Todos los artículos