Errors

When a request fails, the API responds with a non-2xx HTTP status and a JSON body like this:

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

Types and HTTP statusesCopy Anchor Link

Every codeCopy Anchor Link

X-Request-IdCopy Anchor Link

Every response, successful or not, carries the X-Request-Id: req_… header. On errors it also comes in error.request_id. Log it: it is the first thing we will ask for if you contact support (hola@constaia.com).

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

SDK error classesCopy Anchor Link

Every JavaScript SDK error extends ConstaiaError and exposes status, type, code, param, requestId, headers and raw. PHP SDK errors extend Constaia\Exception\ConstaiaException and expose getHttpStatus(), getType(), getErrorCode(), getParam() and getRequestId(). Python SDK errors extend constaia.ConstaiaError and expose .message, .status, .type, .code, .param and .request_id.

In a browser, the Constaia constructor throws an error with code secret_key_in_browser if you pass it a ck_ key: the key must stay on your server. See security.

What to retryCopy Anchor Link

The JavaScript, PHP and Python SDKs already retry the left-hand cases for you (2 retries by default, maxRetries in JavaScript, max_retries in PHP and Python), honour Retry-After and reuse the same Idempotency-Key on every retry, so a retry never charges twice. Set it to 0 to disable retries and handle them yourself. If you make raw HTTP calls, send your own Idempotency-Key on every POST before retrying. See idempotency.

Handling examplesCopy 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: the problem is in the request or the file
    console.error(`Invalid request (${err.code}) at ${err.param ?? "-"}: ${err.message}`);
  } else if (err instanceof InsufficientCreditsError) {
    console.error("Out of credits: buy a pack in the dashboard.");
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited after retrying; try again in ${err.retryAfter ?? 1} s.`);
  } else if (err instanceof APIConnectionError) {
    console.error("Could not reach Constaia:", err.message);
  } else if (err instanceof ConstaiaError) {
    console.error(`Error ${err.status} ${err.code} (request ${err.requestId})`);
  } else {
    throw err;
  }
}

Next stepsCopy Anchor Link