Límites de uso y cuotas

Constaia limita cuántas peticiones puede hacer cada clave de API por segundo para proteger el servicio y repartirlo de forma justa. Esta página explica qué se aplica hoy, qué está en despliegue y cómo diseñar tu integración para no tropezar con los límites.

Qué se aplica hoyCopy Anchor Link

• Por clave de API: cada clave tiene su propio contador. Dos claves de la misma cuenta no se restan entre sí.
• Ventana fija de 1 segundo.
• Límite por defecto: 10 peticiones por segundo. Algunas cuentas tienen un límite configurado distinto; el valor real de tu clave viene siempre en RateLimit-Limit.
• Modo test igual que modo real: las claves ck_test_ tienen el mismo límite de peticiones por segundo (sin cuota de créditos).
• Cuenta cualquier petición autenticada a /v1: analizar, clasificar, listar, consultar un análisis, etc.

CabecerasCopy Anchor Link

Cada respuesta autenticada incluye el estado del límite:

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 429Copy Anchor Link

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

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.

Niveles por plan (en despliegue)Copy Anchor Link

En modo test el límite de peticiones por segundo será el mismo que el de tu nivel, sin cuota de créditos.

Otros límitesCopy Anchor Link

Cómo reintentarCopy Anchor Link

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).

import { Constaia } from "@constaia/sdk";

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

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 clienteCopy Anchor Link

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:

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.

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 lotesCopy Anchor Link

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, responde 202 al momento y te avisa con el webhook batch.completed. Guía completa: lotes masivos.

Controlar el gastoCopy Anchor Link

Mientras tanto:

• 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_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 altosCopy Anchor Link

Si necesitas más peticiones por segundo, escribe a hola@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 pasosCopy Anchor Link