Constaia
Conceptos

Límites de uso y cuotas

Límites por plan de la API de Constaia (peticiones por segundo, análisis simultáneos y páginas por minuto), cabeceras RateLimit, 429 con Retry-After, tope de gasto mensual y cómo reintentar con backoff.

Constaia limita cuántas peticiones puede hacer cada clave de API y cuánto trabajo puede tener en marcha cada cuenta, para proteger el servicio y repartirlo de forma justa. Esta página explica los límites de cada plan, el tope de gasto mensual y cómo diseñar tu integración para no tropezar con ellos.

Límites por plan

NivelPeticiones/sAnálisis simultáneosPáginas/minCuándo
Gratis2260Sin compras
Pago1010600Con algún pack comprado
EmpresaA medidaA medidaA medidaContrato
  • El nivel se calcula solo: tu cuenta pasa a Pago en cuanto compras un pack. El plan Empresa y las cuentas con límites ampliados tienen valores propios. El valor real de tu clave viene siempre en RateLimit-Limit.
  • Peticiones por segundo, por clave de API: cada clave tiene su propio contador (ventana deslizante de 1 s) y cuenta cualquier petición autenticada a /v1: analizar, clasificar, listar, consultar un análisis, etc. Si lo superas: 429 rate_limited.
  • Análisis simultáneos, por cuenta: cuántos análisis síncronos en modo live puede tener la cuenta en curso a la vez. Si lo superas: 429 concurrency_limit. Los análisis con async: true y los lotes no cuentan aquí: van a la cola.
  • Páginas por minuto, por cuenta: páginas analizadas en modo live (síncronas y asíncronas, lotes incluidos) en una ventana deslizante de 60 s. Si lo superas: 429 pages_rate_limited con Retry-After.
  • Modo test: las claves ck_test_ tienen el mismo límite de peticiones por segundo que tu nivel, sin cuota de créditos y sin límite de páginas ni de concurrencia.

Cabeceras

Cada respuesta autenticada incluye el estado del límite:

CabeceraSignificado
RateLimit-LimitPeticiones permitidas en la ventana.
RateLimit-RemainingPeticiones que te quedan en la ventana actual.
RateLimit-ResetSegundos hasta que se reinicia la ventana.
RateLimit-PolicyPolítica aplicada, por ejemplo 10;w=1 (10 peticiones, ventana de 1 s) en el plan de pago o 2;w=1 en el gratuito.
Retry-AfterSolo en 429: segundos que debes esperar.
Respuesta 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01J9Z8Q3K4M5N6P7Q8R9S0T1V2
RateLimit-Limit: 10
RateLimit-Remaining: 7
RateLimit-Reset: 1
RateLimit-Policy: 10;w=1

Las cabeceras RateLimit-* están expuestas por CORS, aunque tu clave nunca debe usarse desde un navegador.

Los SDK guardan las de la última respuesta: constaia.lastRateLimit en JavaScript, $constaia->lastRateLimit en PHP y client.last_rate_limit en Python, con limit, remaining, reset, policy y retryAfter (retry_after en Python).

Respuesta 429

Si superas el límite, recibes 429 con Retry-After:

Respuesta 429
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
RateLimit-Limit: 10
RateLimit-Remaining: 0
RateLimit-Reset: 1
RateLimit-Policy: 10;w=1

{
  "error": {
    "type": "rate_limited",
    "code": "rate_limited",
    "message": "Demasiadas peticiones. Reintenta en un momento.",
    "request_id": "req_01J9Z8Q3K4M5N6P7Q8R9S0T1V3"
  }
}

Una petición rechazada con 429 no llega a procesarse ni se cobra.

Los otros dos límites responden igual, con su propio code y mensaje:

codeLímiteQué hacer
rate_limitedPeticiones por segundo de la clave.Espera Retry-After y reintenta.
concurrency_limitAnálisis síncronos simultáneos de la cuenta.Espera a que terminen los que tienes en curso o usa async: true o lotes.
pages_rate_limitedPáginas por minuto de la cuenta.Espera Retry-After (hasta que se liberan páginas de la ventana de 60 s).

Otros límites

LímiteValorError si lo superas
Tamaño por fichero20 MB413 file_too_large
Páginas de PDF, análisis síncrono30422 too_many_pages
Páginas de PDF, async: true o lotes200422 too_many_pages
Documentos por lote1–100400 batch_too_large / 400 empty_batch
Tipos en expect1–20422 invalid_parameter
metadata20 claves; clave ≤ 40 caracteres; valor ≤ 500422 invalid_parameter
Descarga de file_url15 s, https, IP pública422 file_url_unreachable / 400 invalid_file_url
Idempotency-Key255 caracteres400 invalid_idempotency_key
Resultados por página al listar1–100 (10 por defecto)422 invalid_parameter
Espera en análisis síncrono30 s; después, 202 y resultado por webhook—

Cómo reintentar

Reglas:

  1. Reintenta solo lo reintentable: 429, 409 idempotency_in_progress, 5xx (salvo 501) y errores de red. Ver errores.
  2. En 429, espera exactamente lo que indica Retry-After.
  3. En el resto, usa backoff exponencial con jitter: 0,5 s, 1 s, 2 s, 4 s… con un tope, más un componente aleatorio para que tus procesos no reintenten todos a la vez.
  4. Manda una Idempotency-Key en cada POST y reutilízala en los reintentos, para no cobrar dos veces. Ver idempotencia.
  5. Limita el número de intentos (3–5) y registra el X-Request-Id.

Los SDK de JavaScript, PHP y Python ya lo hacen: reintentan 429, 408, 409 idempotency_in_progress, 5xx (salvo 501) y errores de red, respetan Retry-After (JavaScript y Python esperan como máximo 60 s), usan backoff exponencial con jitter y reutilizan la Idempotency-Key. Por defecto hacen 2 reintentos (maxRetries en JavaScript, max_retries en PHP y Python).

Con el SDK solo tienes que ajustar maxRetries:

src/constaia.ts
import { Constaia } from "@constaia/sdk";

export const constaia = new Constaia({ maxRetries: 4, timeout: 90_000 });

Si llamas a la API con fetch directamente:

src/post-with-retry.ts
const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);

export async function postWithRetry(url: string, body: FormData | string, headers: Record<string, string>, maxRetries = 4) {
  const idempotencyKey = crypto.randomUUID();
  for (let attempt = 0; ; attempt++) {
    try {
      const res = await fetch(url, {
        method: "POST",
        body,
        headers: { ...headers, Authorization: `Bearer ${process.env.CONSTAIA_API_KEY}`, "Idempotency-Key": idempotencyKey },
      });
      const payload = await res.json();
      const inProgress = res.status === 409 && payload?.error?.code === "idempotency_in_progress";
      if ((!RETRYABLE.has(res.status) && !inProgress) || attempt >= maxRetries) {
        if (!res.ok) throw Object.assign(new Error(payload.error?.message), { status: res.status, error: payload.error });
        return payload;
      }
      const retryAfter = Number(res.headers.get("retry-after"));
      await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : backoff(attempt));
    } catch (err) {
      if ((err as { status?: number }).status || attempt >= maxRetries) throw err;
      await sleep(backoff(attempt)); // error de red
    }
  }
}

const backoff = (attempt: number) => Math.min(8000, 500 * 2 ** attempt) * (0.5 + Math.random() / 2);
const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

Limita la concurrencia en tu cliente

Reintentar bien no basta si lanzas cientos de análisis a la vez: la mayoría acabarán en 429. Limita cuántas peticiones tienes en vuelo. Los tres SDK lo hacen en el cliente (4 por defecto); las peticiones que sobran esperan su turno:

SDKOpción
JavaScriptnew Constaia({ maxConcurrency: 4 })
PHPnew Client(null, ['max_concurrency' => 4]), usado por analyzeMany() para analizar en paralelo
PythonConstaia(max_concurrency=4) o AsyncConstaia(max_concurrency=4), con hilos o tareas de asyncio

El límite es por cliente (por proceso). Con varios workers, el límite por segundo de la clave es compartido: mantén concurrencia × workers acorde con él.

scripts/analyze-folder.ts
import { readdir } from "node:fs/promises";
import path from "node:path";
import { Constaia } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const constaia = new Constaia({ maxConcurrency: 4, maxRetries: 4 }); // como máximo 4 peticiones en vuelo

const dir = process.argv[2] ?? "./docs";
const files = (await readdir(dir)).filter((f) => /\.(jpe?g|png|webp|heic|pdf)$/i.test(f));

const results = await Promise.all(
  files.map(async (name) => {
    const analysis = await constaia.analyze(await fromPath(path.join(dir, name)), { expect: "es_dni" });
    return { name, status: analysis.verdict?.status };
  }),
);
console.table(results);

Sin SDK, limita tú la concurrencia: p-limit en JavaScript o un asyncio.Semaphore en Python.

Mucho volumen: usa lotes

Para procesar cientos de documentos, un lote es más eficiente que cientos de llamadas: una sola petición POST /v1/batches admite hasta 100 documentos, cuenta como una petición para el límite por segundo, no ocupa huecos de análisis simultáneos, responde 202 al momento y te avisa con el webhook batch.completed. Sus páginas sí cuentan para el límite de páginas por minuto: en el plan gratuito (60 páginas/min), un lote con más páginas se rechaza entero con 429 pages_rate_limited, así que divídelo o espera Retry-After. Guía completa: lotes masivos.

Controlar el gasto

Tope de gasto mensual

Puedes fijar un tope de créditos al mes para la cuenta (monthly_credit_cap). Cuenta los créditos cobrados en modo live durante el mes natural (UTC) y se reinicia el día 1:

  • Si un análisis haría superar el tope, se rechaza con 402 monthly_cap_reached antes de procesarse y no se cobra. Los lotes y los análisis asíncronos se comprueban igual.
  • Los owners y admins de la cuenta reciben un email al llegar al 80 % y al 100 % del tope (una vez por nivel y mes). Cambiar el tope reinicia los avisos del mes.
  • El modo test no cuenta.
402 monthly_cap_reached
{
  "error": {
    "type": "insufficient_credits",
    "code": "monthly_cap_reached",
    "message": "Se ha alcanzado el tope de gasto mensual de la cuenta (1000 créditos). Súbelo en el panel o espera al día 1.",
    "request_id": "req_01J9Z8Q3K4M5N6P7Q8R9S0T1V4"
  }
}

No reintentes un 402: sube el tope o espera al mes siguiente. El tope todavía no se puede fijar desde el panel: escríbenos a support@constaia.com con el valor que quieres.

Además:

  • Configura el umbral de saldo bajo en el panel y suscríbete al webhook credits.low (solo modo real, se envía una vez hasta que recargues). Ver webhooks.
  • Consulta GET /v1/balance antes de trabajos grandes. Lo que puedes gastar es credits_spendable (credits_available + free_tier_remaining).
  • Desarrolla y prueba con claves ck_test_: nunca cobran. Ver modo test.

Más en créditos y facturación.

Pedir límites más altos

Si necesitas más peticiones por segundo, análisis simultáneos o páginas por minuto, escribe a support@constaia.com con tu cuenta, el volumen previsto (documentos al día y picos) y el caso de uso. Los límites se pueden ampliar por cuenta. El plan Empresa incluye límites a medida.

Siguientes pasos

En esta página