Errors reference · LegalCloud

This page lists the errors the API can return and how to handle them.

Error format

Errors are JSON with the HTTP status and a body like:

{
  "success": false,
  "error": "The token lacks the required scope",
  "code": "SCOPE_FORBIDDEN"
}

Use the HTTP status to decide the type of error and code to react programmatically. The error text is for humans and may change.

HTTP status codes

Status	Meaning	What to do
`200`, `201`	Success	—
`400`	Invalid request (bad JSON, missing or invalid fields)	Fix the request; do not retry as is
`401`	Missing, invalid, revoked or expired token	Check the token (see below)
`403`	The token lacks the scope, or your plan does not include the feature or limit	Use a token with the right scope or upgrade the plan
`404`	The resource does not exist, or it is not in your organization	Check the identifier
`429`	Monthly quota or per-minute rate limit exceeded	Wait and retry (see `Retry-After`)
`5xx`	Temporary problem on our side	Retry with exponential backoff

Authentication errors (401)

`code`	Meaning
`TOKEN_MISSING`	No `Authorization` header
`TOKEN_INVALID`	The token does not exist or is malformed
`TOKEN_REVOKED`	The token was revoked
`TOKEN_EXPIRED`	The token passed its expiry date

Authorization and plan errors (403)

`code`	Meaning
`SCOPE_FORBIDDEN`	The token lacks the scope required by the endpoint
`PLAN_UPGRADE_REQUIRED`	The feature is not included in your plan
`LANGUAGE_LIMIT_REACHED`	You reached the number of languages of your plan
`TOKEN_LIMIT_REACHED`	You reached the number of API tokens of your plan
`UNSUPPORTED_LANGUAGE`, `LANGUAGE_NOT_SELECTED`	The language is not available for your organization

Other code values can appear on specific endpoints; the interactive console documents the status codes of each one.

Public page errors

GET /d/{hash} answers:

401 with TOKEN_MISSING, TOKEN_INVALID, TOKEN_REVOKED or TOKEN_EXPIRED when the document requires a token.
403 (HTML page) when the visitor's country or the embedding site is not allowed.
404 when the document does not exist or is not published.

Rate limiting (429)

Every response to a token call includes X-Quota-* and X-RateLimit-* headers. When a limit is exceeded the API answers 429; wait until the reset time (X-RateLimit-Reset for the per-minute limit, X-Quota-Reset for the monthly quota) or until the Retry-After header says. If you need more calls, buy an API calls add-on or upgrade your plan.

Retrying safely

Retry 429 and 5xx with exponential backoff and jitter.
Do not retry 400, 401, 403 or 404: the request must change first.
GET requests are safe to retry. For POST requests that create documents, check whether the first attempt succeeded before repeating it.

async function callApi(url, token, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
    if (res.status !== 429 && res.status < 500) return res;
    const wait = Number(res.headers.get("Retry-After")) || 2 ** i;
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error("LegalCloud API unavailable");
}

Getting help

If an error persists, open a ticket from Support in the dashboard and include the HTTP status, the code and the time of the request.

Last updated: 2026-10-27