Errores

Cuando una petición falla, la API responde con un estado HTTP distinto de 2xx y un cuerpo JSON con esta forma:

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_parameter",
    "message": "Tipo de documento desconocido. Consulta GET /v1/document-types.",
    "param": "options.expect",
    "request_id": "req_01J9Z8Q3K4M5N6P7Q8R9S0T1V2"
  }
}

Tipos y estados HTTPCopy Anchor Link

Todos los códigosCopy Anchor Link

X-Request-IdCopy Anchor Link

Todas las respuestas, correctas o no, llevan la cabecera X-Request-Id: req_…. En los errores también viene en error.request_id. Guárdalo en tus logs: es lo primero que te pediremos si escribes a soporte (hola@constaia.com).

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Request-Id: req_01J9Z8Q3K4M5N6P7Q8R9S0T1V2

Clases de error en los SDKCopy Anchor Link

Todos los errores del SDK de JavaScript extienden ConstaiaError y exponen status, type, code, param, requestId, headers y raw. Los del SDK de PHP extienden Constaia\Exception\ConstaiaException y exponen getHttpStatus(), getType(), getErrorCode(), getParam() y getRequestId(). Los del SDK de Python extienden constaia.ConstaiaError y exponen .message, .status, .type, .code, .param y .request_id.

En un navegador, el constructor de Constaia lanza un error con código secret_key_in_browser si le pasas una clave ck_: la clave debe quedarse en tu servidor. Ver seguridad.

Qué reintentarCopy Anchor Link

Los SDK de JavaScript, PHP y Python ya reintentan por ti los casos de la columna izquierda (2 reintentos por defecto, maxRetries en JavaScript, max_retries en PHP y Python), respetan Retry-After y reutilizan la misma Idempotency-Key en cada reintento, así que un reintento nunca cobra dos veces. Con 0 desactivas los reintentos y los gestionas tú. Si haces llamadas HTTP directas, manda tú una Idempotency-Key en cada POST antes de reintentar. Ver idempotencia.

Ejemplos de manejoCopy Anchor Link

import {
  Constaia,
  ConstaiaError,
  InsufficientCreditsError,
  InvalidRequestError,
  RateLimitError,
  APIConnectionError,
} from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const constaia = new Constaia({ maxRetries: 3 });

try {
  const analysis = await constaia.analyze(await fromPath("./dni.jpg"), { expect: "es_dni" });
  console.log(analysis.verdict?.status);
} catch (err) {
  if (err instanceof InvalidRequestError) {
    // 400/409/413/415/422: el problema está en la petición o en el fichero
    console.error(`Petición no válida (${err.code}) en ${err.param ?? "-"}: ${err.message}`);
  } else if (err instanceof InsufficientCreditsError) {
    console.error("Sin créditos: compra un pack en el panel.");
  } else if (err instanceof RateLimitError) {
    console.error(`Límite alcanzado tras reintentar; vuelve a probar en ${err.retryAfter ?? 1} s.`);
  } else if (err instanceof APIConnectionError) {
    console.error("No se pudo conectar con Constaia:", err.message);
  } else if (err instanceof ConstaiaError) {
    console.error(`Error ${err.status} ${err.code} (request ${err.requestId})`);
  } else {
    throw err;
  }
}

Siguientes pasosCopy Anchor Link