Límites de frecuencia y cuotas#

EnConvert mide una sola cosa: la operación. Tu plan compra un número de operaciones al mes, además de un tope de subida, una ventana de retención y un tamaño de lote. Esta página explica qué es una op, qué incluye cada plan y qué código de estado recibes al pasarte.

Dos límites se confunden con facilidad. La asignación mensual responde 402. El limitador de frecuencia de solicitudes en ventanas cortas responde 429. Son sistemas separados y ninguno sustituye al otro.

Qué cuenta como una operación#

Una op es una unidad de trabajo. Todos los endpoints cobran la misma op por la misma unidad, sin multiplicadores ni contadores por endpoint. Tampoco se factura por tiempo de renderizado: una página que tarda 30 segundos en renderizarse cuesta exactamente lo mismo que una que tarda dos segundos.

La unidad en sí varía según el endpoint, porque «una unidad de trabajo» significa algo distinto para un solo archivo que para un rastreo:

Lookup, distill, discover y watch están en beta privada: se pueden llamar hoy, pero no están anunciados ni tienen disponibilidad general. Las reglas de recuento de arriba se les aplican tal cual; consulta Próximamente.

Hay dos reglas más que se aplican en todas partes. Las ops se cuentan al completarse, así que una solicitud fallida no consume tu asignación. Y una solicitud de varias unidades se comprueba de antemano: un lote de 40 URLs se mide contra tu asignación restante antes de obtener ninguna URL, de modo que se rechaza entero en lugar de procesarse a medias.

Las llamadas de solo lectura son gratuitas. Consultar un trabajo, listar tus trabajos de ingesta o tus watchers y descargar un artefacto terminado no consumen nada.

Planes#

Todos los números de abajo los aplica la API; no son aspiracionales. La columna de slug es lo que ves en las respuestas de la API (por ejemplo, el campo tier en un 413); el nombre es lo que ves en la página de precios y en una factura.

Los límites de Enterprise se fijan por contrato y no a partir de esta tabla.

La asignación de Founding es fácil de gastar sin querer. 500 ops son 500 páginas, y un solo rastreo puede llevárselas todas en una única llamada, así que limita max_pages antes de apuntar ingest a un sitio de documentación.

Las ops se reinician al comienzo de cada ciclo de facturación y no se acumulan. El tope de subida se comprueba contra el recuento exacto de bytes de la parte subida antes de que empiece cualquier conversión, y un archivo cuyo tamaño sea exactamente el tope se acepta. La retención es cuánto tiempo permanece en almacenamiento un artefacto producido; la URL firmada que apunta a él vive 15 minutos y puede volver a firmarse desde el endpoint de estado hasta que se cierre la ventana de retención, algo que se cubre en URLs firmadas.

Asignaciones que no son ops#

Junto al contador de ops hay dos asignaciones que nunca consumen de él.

Los créditos de IA no usados se acumulan al periodo siguiente. Quedarte sin ellos no hace fallar una solicitud: la extracción de esquema recurre a su resultado heurístico y CSS, y la llamada sigue teniendo éxito. Los watchers son una plaza que ocupas y no consumo, así que un watcher inactivo no cuesta nada y uno ocupado tampoco. El tope está en cuántos existen a la vez.

Cuando se agota la asignación mensual#

La API responde 402 Payment Required, nunca 429, y el cuerpo tiene la forma estándar {"detail": "..."}.

{
    "detail": "Monthly operations limit reached (500/500). Upgrade your plan to continue."
}

En esta ruta existen tres mensajes:

Cuando el contador llega al 100 por cien por primera vez, el propietario del proyecto recibe además un correo, como mucho uno cada 24 horas.

Excedente#

El excedente está disponible en todos los planes de pago, a $0.02 por operación, y está desactivado por defecto. Actívalo y las solicitudes que pasen de tu asignación siguen funcionando, más allá de 3.000 en Indie, 15.000 en Studio y 50.000 en Production, con las ops extra facturadas a esa tarifa. Déjalo desactivado y la asignación es un tope estricto hasta el siguiente ciclo, que es justo el objetivo: un bucle descontrolado no puede costarte dinero en silencio. En el plan gratuito Founding el tope estricto es el único comportamiento; Enterprise se rige por contrato.

Saber en qué punto estás#

No hay ningún encabezado para esto. Las respuestas correctas no llevan recuento de ops restantes ni campos de uso de ningún tipo, así que las únicas formas de conocer tu posición son el panel y tu propia contabilidad de solicitudes. Planifica para el 402 en lugar de esperar a que te avisen.

Límites de frecuencia de solicitudes#

Al margen de la asignación mensual, las solicitudes también están limitadas en ventanas cortas para que un proyecto no pueda desplazar al resto. Corren tres ventanas a la vez: por minuto, por hora y por día. Los límites escalan con tu plan.

Los números exactos de cada ventana no se publican aquí. Léelos de la respuesta: un rechazo te dice el límite que saltó y cuánto hay que esperar, y ese es el valor que la API está aplicando realmente.

Lo que sí es fijo es el comportamiento:

• Los límites se aplican por proyecto, no por clave de API, así que rotar claves no reinicia una ventana.
• El tráfico público (pk_) y el privado (sk_) usan cubos separados, y el tráfico de clave pública lleva además un tope por IP por debajo de la ventana del proyecto.
• Solo se limitan las solicitudes POST que hacen trabajo: los endpoints de conversión, los endpoints V2 y la emisión de tokens. Todos los GET están exentos, así que consultar estados y descargar no hará saltar nada.

Un rechazo es 429 Too Many Requests:

{
    "detail": "Rate limit exceeded. Please slow down and retry shortly."
}

Lleva cuatro encabezados:

Tanto RateLimit-Reset como Retry-After son segundos enteros y nunca bajan de 1. Esperar los segundos indicados y reintentar una vez es todo el procedimiento de recuperación.

Límites que no son 429#

La mayoría de las respuestas de límite no vienen del limitador de frecuencia. Estas son las que la gente encuentra.

413: la subida es demasiado grande#

Superar el tope de subida de tu plan devuelve 413 con un objeto estructurado como valor de detail. Lee body.detail.max_size, no body.max_size.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

POST /v2/ingest/files es la excepción: responde 413 con una cadena simple, File '{filename}' exceeds the {max_size}-byte limit.

403: una función de lotes o de V1 que tu plan no tiene#

402: un endpoint V2 desactivado, u otro tope#

Las comprobaciones de los endpoints V2 responden 402 en lugar de 403, la única asimetría de este esquema que merece la pena memorizar:

503: el servicio está ocupado, no tú#

The conversion service is at capacity. Please retry shortly. (enviado con Retry-After: 30) y Server is at capacity. Please retry shortly. (enviado con Retry-After: 10) son controles de capacidad de nuestro lado. No se te contabilizan y no son limitación de frecuencia. Lee Retry-After en lugar de suponer que una sola espera vale para ambos.

Páginas relacionadas#

• Errores recoge todos los códigos de estado y mensajes que la API puede devolver.
• Procesamiento por lotes cubre cómo interactúa el límite de lote con la salida ZIP y el polling.
• Ingesta de archivos cubre las rutas de subida a las que se aplica el tope de tamaño.
• URLs firmadas cubre la ventana de descarga de 15 minutos que vive dentro de tu ventana de retención.