SLA and status

Health endpointCopy Anchor Link

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

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

The response may include more diagnostic fields (for example storage and processing). Don't depend on them: use the HTTP status and status to decide.

/health needs no API key and does not count towards your rate limit. Use it in your monitoring (one check per minute is enough) or in your own application's health check if you want to degrade features when Constaia is unavailable.

SupportCopy Anchor Link

Write to hola@constaia.com. To help us help you quickly, include:

• The X-Request-Id (req_…) of the affected requests. It comes in every response and, on errors, also in error.request_id.
• The analysis or batch id (an_…, bat_…) if you have it.
• The approximate time (with time zone) and whether you used a test or live key.

Never send your API key or real documents by email.

SLACopy Anchor Link

If you need an SLA, write to hola@constaia.com. Plans and prices on pricing.

Make your integration resilientCopy Anchor Link

Even when the API is up, a document can take a while, the network can drop or you can hit the rate limit. Design for it:

Generous timeouts for synchronous analyses. The API waits up to 30 s before answering 202. Set a timeout of 60 s or more in your HTTP client (the SDKs use 60 s by default). A 10 s timeout would cut analyses that were about to finish fine.

Async and webhooks for long documents. For many-page PDFs, batches or when you don't want to block a user request, use async: true or batches and get the result by webhook. If the webhook doesn't arrive (your server was down), call GET /v1/analyses/{id}: Constaia retries deliveries for about 3 days.

Treat 202 as normal. Even for a synchronous request, if it takes longer than 30 s you get 202 with status: "queued" or "processing". Store the id and wait for the webhook.

Retries with backoff and idempotency. Retry 429, 5xx and network errors honouring Retry-After, and always send an Idempotency-Key so you are never charged twice. The SDKs already do this. See rate limits and idempotency.

A plan B in your product. If Constaia doesn't respond after retrying, don't block the user: accept the document as pending and analyse it later, or send it to human review.

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 }; // store the file and retry from a queue
    }
    throw err;
  }
}

Next stepsCopy Anchor Link