SLA y estado

Endpoint de saludCopy Anchor Link

curl -i https://api.constaia.com/health

{ "status": "ok", "postgres": true, "valkey": true }

La respuesta puede incluir más campos de diagnóstico (por ejemplo storage y processing). No dependas de ellos: para decidir, usa el estado HTTP y status.

/health no necesita clave de API y no cuenta para tu límite de peticiones. Úsalo en tu monitorización (un chequeo cada minuto es suficiente) o en el health check de tu propia aplicación si quieres degradar funciones cuando Constaia no esté disponible.

SoporteCopy Anchor Link

Escribe a hola@constaia.com. Para que podamos ayudarte rápido, incluye:

• El X-Request-Id (req_…) de las peticiones afectadas. Viene en todas las respuestas y, en los errores, también en error.request_id.
• El id del análisis o del lote (an_…, bat_…) si lo tienes.
• La hora aproximada (con zona horaria) y si usabas una clave de test o live.

No mandes nunca tu clave de API ni documentos reales por email.

SLACopy Anchor Link

Si necesitas un SLA, escribe a hola@constaia.com. Planes y precios en precios.

Haz tu integración resistenteCopy Anchor Link

Aunque la API esté disponible, un documento puede tardar, la red puede cortarse o puedes llegar al límite de peticiones. Diseña para ello:

Tiempos de espera generosos en análisis síncronos. La API espera hasta 30 s antes de responder 202. Configura en tu cliente HTTP un timeout de 60 s o más (los SDK usan 60 s por defecto). Un timeout de 10 s cortaría análisis que iban a terminar bien.

Asíncrono y webhooks para documentos largos. Para PDF de muchas páginas, lotes o cuando no quieres bloquear una petición de tu usuario, usa async: true o lotes y recibe el resultado por webhook. Si el webhook no llega (tu servidor estaba caído), consulta GET /v1/analyses/{id}: Constaia reintenta las entregas durante unos 3 días.

Trata el 202 como normal. Aunque pidas un análisis síncrono, si tarda más de 30 s recibes 202 con status: "queued" o "processing". Guarda el id y espera al webhook.

Reintentos con backoff e idempotencia. Reintenta 429, 5xx y errores de red respetando Retry-After, y manda siempre Idempotency-Key para no cobrar dos veces. Los SDK ya lo hacen. Ver límites de uso e idempotencia.

Plan B en tu producto. Si Constaia no responde tras los reintentos, no bloquees al usuario: acepta el documento como pendiente y analízalo más tarde, o mándalo a revisión humana.

import { Constaia, APIConnectionError, APIError } from "@constaia/sdk";

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

export async function verify(file: Blob, filename: string) {
  try {
    const analysis = await constaia.analyze({ file, filename }, { expect: "es_dni" });
    if (analysis.status !== "completed") return { state: "pending" as const, id: analysis.id };
    return { state: "done" as const, status: analysis.verdict?.status ?? null, id: analysis.id };
  } catch (err) {
    if (err instanceof APIConnectionError || err instanceof APIError) {
      return { state: "retry_later" as const }; // guarda el fichero y vuelve a intentarlo desde una cola
    }
    throw err;
  }
}

Siguientes pasosCopy Anchor Link