Error responses and codes

This page lists every error code a caller of the REFRACT Dispatcher API can receive: /api/render, the Power Platform connector routes (/api/gateway/v1/...), and the workflow, eSign, Delivery, batch, document access, and verification routes. It covers what an error answer looks like, which headers carry the reason, and when a request may be sent again.

The signing portal's own calls (between a signer's browser, the portal, and the Dispatcher) use further codes. They are not part of this contract and are not listed here.

The Error Body

A refusal answers with a JSON body:

{
  "error": "Service Unavailable",
  "code": "LICENSE_UNAVAILABLE",
  "message": "The licensing service did not answer.",
  "correlationId": "3f2c9a1e-7b4d-4c1a-9e2f-5d6b8a0c1e47",
  "retryable": true,
  "detail": "The licensing service did not answer."
}

One 503 has error and code only: consent_layer_unavailable when it is found after the signing request was recorded (the request is then cancelled).

Some codes add fields beside these: feature (FEATURE_NOT_LICENSED), role (ROLE_MISSING), setting (SECTION508_SETTING_REFUSED), failedStandards (ACCESSIBILITY_CHECK_FAILED), state (WORKFLOW_STATE_CHANGED), problems (WORKFLOW_ROUTING_INVALID), fieldErrors (WORKFLOW_INITIAL_DATA_INVALID), and plan and expiresAt (the licence codes from /api/render).

Answers With a PDF Body

A render that fails for a reason of the service's own answers 500 with an error-report PDF as the body. So does an eSign or Delivery step refused after the document was rendered and stored; a workflow refused after the document was stored answers 422 the same way. The code is in the X-Refract-ErrorCode header, not in a body. The tables below mark these answers PDF, and after render when the document already exists.

Answers Without a Code

A few answers carry no code at all. Handle them by status:

• The explain and accessibility trace routes (/api/explain/..., /api/accessibility/...) answer their 4xx and 500 with error only.
• A 500 or 502 JSON answer from a route other than /api/render carries error, and sometimes detail, but no code.
• An unexpected exception that no route handles answers 500 with an empty body.
• A failed operation reported by GET /api/operation-status/... answers 200 with status: "failed" and a failureReason sentence.

Error Headers

On a failed answer to /api/render, Access-Control-Expose-Headers lists these headers so that browser code on another origin can read them. Errors on the API overview describes the render answers in more detail.

When to Retry

1. Retry only when retryable is true. These answers say that nothing was done and the same request can succeed later. Every one of them carries Retry-After.
2. Honour Retry-After. Wait at least that many seconds before the next try. Stop after a few tries and report the correlation ID.
3. Never retry a 4xx. The same request gets the same answer; fix what the code names. The one exception is 429 TOO_MANY_REQUESTS from the connector routes, a rate limit: wait for Retry-After, then send again. The monthly limits (DOCUMENT_QUOTA_EXCEEDED, monthly_hard_cap_reached, and the others under Licence and limits) are also 429, and are not retried.
4. Do not resend a 5xx without "retryable": true automatically. Some of these carry Retry-After and say in message that a later try may work; a person may resubmit after that wait. Keep the correlation ID and, for a PDF body, the error report.

async function callDispatcher(url, init, maxTries = 3) {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(url, init);
    if (res.ok) return res;

    const isJson = (res.headers.get('Content-Type') ?? '').includes('application/json');
    const body = isJson ? await res.json() : null;
    const code = body?.code ?? res.headers.get('X-Refract-ErrorCode');
    const retryAfter = Number(res.headers.get('Retry-After') ?? 0);

    const rateLimited = res.status === 429 && code === 'TOO_MANY_REQUESTS';
    if ((body?.retryable === true || rateLimited) && attempt < maxTries) {
      await new Promise((r) => setTimeout(r, Math.max(retryAfter, 1) * 1000));
      continue;
    }
    const correlationId = res.headers.get('X-Refract-CorrelationId');
    throw Object.assign(new Error(body?.message ?? `HTTP ${res.status}`), { status: res.status, code, correlationId });
  }
}

Codes by Area

Status is the HTTP status; a code with more than one lists each. PDF means the body is an error-report PDF and the code is in X-Refract-ErrorCode. After render means the document was rendered and stored before the step was refused, and the code is also in X-Refract-LifecycleErrorCode. Retryable is Yes when the body says "retryable": true, No (false) when the body says "retryable": false, and No when the body has no retryable field. Retry-After is the header's value in seconds.

Licence and limits

Render and storage

Accessibility

Workflow

eSign

Consent

Delivery and batch

Authentication and access

Requests

Next Steps

• REFRACT Dispatcher API - Endpoints, response headers, and how a failed render answers
• Authentication - Tokens, roles, and who may call
• Power Platform API Reference - The connector's actions and their error responses
• Power Platform Connector Setup - Connection setup and troubleshooting