Error Handling

The widget handles most errors internally and displays user-friendly messages. For deeper control, listen to the error events and react accordingly.

Error Events

allfeat:failed — Critical Errors

Emitted when the operation cannot continue. The widget shows an error screen (FAILED or DISABLED).

widget.addEventListener('allfeat:failed', (e) => {
  const { code, message, requestId, details } = e.detail;

  console.error(`[${code}] ${message} (${requestId})`);

  // Example: redirect on configuration error
  if (code === 'session.origin_not_allowed') {
    showMessage('This website is not authorized to use the widget.');
  }
});

allfeat:error — Non-Fatal Errors

Emitted for recoverable errors. The widget continues operating.

widget.addEventListener('allfeat:error', (e) => {
  const { code, message, requestId, stage } = e.detail;

  sendToMonitoring({
    code,
    message,
    requestId,
    stage,
  });
});

allfeat:token-expired — Authentication Errors

See Authentication for the full token refresh flow.

Error Categories

| Category | Example Codes | Widget Behavior | |----------|---------------|----------------| | Auth / Session | session.invalid_token, common.auth.expired | Triggers token refresh flow | | Configuration | session.key_inactive, session.origin_not_allowed, organization.inactive | DISABLED screen (no retry button) | | Service Unavailable | common.service_unavailable, transaction.store_unavailable | FAILED screen with retry | | Rate Limited | common.rate_limited, session.rate_limited | FAILED screen with message | | Other API Errors | registration.duplicate_title, work.not_found | FAILED screen with localized message | | Client Errors | widget.network_error, widget.upload_error | FAILED screen, no request ID |

Note

See the full Error Codes Reference for every error code, its user-facing message, and recommended integrator action.

Request ID

Every API error includes a request_id (e.g., req_01HXYZ8G7K3M9Q2F4N5P6R7S8T). This ID is:

• Shown on terminal screens (FAILED, DISABLED) with a copy button
• Included in allfeat:failed and allfeat:error event payloads as requestId
• Useful for support tickets — it correlates to server-side logs

Client-side errors (widget.* codes) do not have a request ID.

Retry Behavior

| Scenario | Behavior | |----------|----------| | File upload | 3 total attempts (2 retries) with exponential backoff (1s, 2s) | | Token expiry | Pauses and waits for a new token (60-second timeout) | | Rate limiting (429) | Up to 2 retries with backoff (1s, 2s, or Retry-After header) | | Transaction polling | Polls every 3s with a 120-second timeout | | Configuration errors | Not retryable — DISABLED screen without retry button | | Network errors | Displayed to the user with a FAILED screen (retry button) |

Resetting After an Error

Call widget.reset() to clear the error state and return to the form:

widget.addEventListener('allfeat:failed', (e) => {
  retryButton.onclick = () => widget.reset();
});

Getting the Current State

Use getState() to inspect the widget’s current state for debugging:

const state = widget.getState();
console.log(state);
// {
//   screen: 'FAILED',
//   jobId: '...',
//   transactionId: '...',
//   atsId: null,
//   accessCode: undefined
// }