Guía del producto y de la API

Errores

Los errores se devuelven como problem+json conforme a RFC 9457. Todas las respuestas incluyen correlationId; indícalo al contactar con soporte.

Estado	Significado	Qué hacer
`401`	Clave ausente o no válida	Comprueba la cabecera X-PDFgine-Key y que la clave no se haya revocado.
`402`	Cuota agotada	Mejora el plan o espera a que se renueve el período.
`404`	Plantilla o documento no encontrado	Comprueba el código de plantilla y que tenga una revisión publicada.
`429`	Límite de solicitudes superado	Espera los segundos indicados en la cabecera Retry-After y vuelve a intentarlo.

Los límites de solicitudes dependen del plan

Los límites por minuto y por hora de los endpoints de generación se aplican por ORGANIZACIÓN y proceden de tu plan; se muestran en la tabla siguiente. Como se cuentan por organización y no por clave, añadir otra clave API no los aumenta. Una respuesta 429 identifica la ventana alcanzada en la cabecera X-PDFgine-RateLimit-Scope: tenant-api, tenant-render-minute o tenant-render-hour. Para trabajos masivos, envía hasta 100 documentos en una solicitud /document-batches en lugar de un documento por solicitud.

La respuesta cuando se agota la cuota

HTTP/1.1 402 Payment Required
X-PDFgine-Quota-Remaining: 0
X-PDFgine-Metering-Basis: pdf-equivalent

{
  "title": "Cuota de páginas superada",
  "status": 402,
  "detail": "Tu plan ha agotado su cuota de páginas disponible.",
  "correlationId": "114249cb1dbc52a29026ab2eca5c4b72"
}

Retry-After y la ventana

Se aplican dos límites consecutivos. El primero protege el servicio y se cuenta por credencial: 30 solicitudes por ventana sin clave y 120 con clave, en una ventana de 60 segundos. El segundo procede de tu plan y se cuenta por organización.

Plan	Documentos / minuto	Documentos / hora
Gratis	15	150
Go	30	300
Pro	60	600
Max	300	3.000

HTTP 429

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-PDFgine-RateLimit-Scope: tenant-render-minute

{
  "title": "Too many requests",
  "status": 429,
  "detail": "The request limit was exceeded. Please try again later.",
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

La ventana es fija, no deslizante: comienza con la primera solicitud, todas las que llegan dentro consumen la misma cuota y después el contador se reinicia. Retry-After indica los segundos restantes; basta esperar ese tiempo y reintentar antes solo provoca otro rechazo.

Los errores más habituales

Un 4xx repetido sin cambios vuelve a fallar. Estos códigos indican que la solicitud es incorrecta, no que el servicio esté ocupado; solo merece la pena reintentar 429 y 5xx.
En un 429, la respuesta ya incluye Retry-After. Elegir la espera a ojo hace perder tiempo o provoca directamente otro rechazo.
402 no es una avería por la que despertar a alguien a las tres de la mañana. Significa que se ha agotado el mes; supervisa X-PDFgine-Quota-Remaining y mejora el plan antes de que ocurra.
Un 410 al descargar no significa que se haya perdido el archivo. Terminó la conservación: el documento se generó, se contabilizó y después se eliminó según el calendario del plan.
Guardar solo el código de estado convierte una solicitud de soporte en un juego de adivinanzas. Guarda también correlationId; ese valor permite encontrar la solicitud.