Error Handling

Reliable error handling is essential for shop integrations. Sync operations can fail for many reasons — network issues, rate limits, validation errors, or platform downtime. A good error handling strategy makes failures visible, recoverable, and non-blocking.

Error Categories

Category	Examples	Response
Transient	Network timeout, 5xx server error, rate limit	Retry automatically
Validation	Missing required field, invalid data format	Log and skip, fix transform logic
Permanent	Entity deleted, authentication revoked	Log, alert user, stop retrying
Configuration	Missing mapping, wrong API key	Log, alert user

Logging

Use the framework's log() function to write structured log messages:

const { log } = require('@vario-software/vario-app-framework-backend/utils/logger');

// Log levels: DEBUG, INFO, WARN, ERROR
await log('Starting article sync for channel X', 'services/sync', 'INFO');
await log(`Article ${articleId} synced successfully`, 'services/sync', 'INFO');
await log(`Rate limit warning: 80% consumed`, 'services/sync', 'WARN');
await log(`Failed to sync article ${articleId}: ${error.message}`, 'services/sync', 'ERROR');

What to Log

• Sync start/end — When a sync cycle begins and completes

• Entity processing — Which entities are being processed

• API calls — Outgoing requests to the platform (consider masking sensitive data)

• Errors — Full error details including response body from the platform

• Queue state — Items queued, processed, failed

Masking Sensitive Data

When logging API requests that contain credentials, use the secret option:

const result = await new ErpApi('/some/endpoint', {
  method: 'POST',
  body: JSON.stringify({ apiKey: 'secret', data: 'payload' }),
  secret: true,
  secretsToMask: ['apiKey']
});

HttpError

The framework provides the HttpError class for structured error responses:

const { HttpError } = require('@vario-software/vario-app-framework-backend/utils/httpError');

// Throw a structured error
throw new HttpError(
  'Article not found on platform',   // message
  404,                                // statusCode
  'services/sync',                    // logService
  { articleId, platformId },          // logInfo
  'ARTICLE_NOT_FOUND',               // logId
  'ERROR'                             // logLevel
);

HttpError is automatically caught by the framework's exception handler, which:

• Sends a JSON error response to the client

• Logs the error with full context

• Prevents duplicate error handling

Queue Error Tracking

When using a queue (see Queue-Based Processing), track errors per work item:

• Attempt count — How many times processing was attempted

• Last error message — What went wrong on the last attempt

• Error details — HTTP status code, platform error response, timestamp

This information helps users debug sync issues and decide whether to retry or investigate.

Retry Strategies

Automatic Retry (Transient Errors)

For transient errors (network issues, rate limits, 5xx responses), retry automatically with backoff:

• Immediate retry — For very transient issues (e.g., single network blip)

• Exponential backoff — Wait 1s, 2s, 4s, 8s, etc. between retries

• Maximum attempts — Stop after N attempts (e.g., 3-5) and mark as failed

The framework's Api class automatically retries HTTP 429 (rate limit) responses with exponential backoff. You don't need to handle this yourself for ERP API calls.

Manual Retry (Permanent or Unknown Errors)

For errors that can't be automatically resolved, let users retry manually:

• Provide a "Retry" button in the queue UI

• Reset the queue item state from FAILED to QUEUED

• Clear the error information

No Retry (Permanent Errors)

Some errors should not be retried:

• Entity was deleted (404) — The source data no longer exists

• Authentication revoked (401/403) — Credentials need to be renewed

• Validation rejected permanently — The data doesn't meet platform requirements

Mark these as permanently failed and inform the user.

Error Notifications

For critical errors that require user attention, surface them clearly:

• Dashboard widget — Show a count of failed queue items

• Email notification — Alert the user when sync errors accumulate

• In-app notification — Show a warning banner in the settings UI

Non-Blocking Error Handling

A failure in one sync operation should not block others:

async function processQueueBatch(items)
{
  for (const item of items)
  {
    try
    {
      await processSyncItem(item);
      await markAsCompleted(item.id);
    }
    catch (error)
    {
      // Log the error and continue with the next item
      await log(
        `Failed to process ${item.topic} for ${item.entityId}: ${error.message}`,
        'queue',
        'ERROR'
      );
      await markAsFailed(item.id, error);
      // Don't throw — continue processing other items
    }
  }
}

Webhook Error Handling

Webhook handlers should never fail visibly. Even if processing fails, the webhook response should be 200 OK:

app.apiServer.post('/webhooks/article-update', async (req, res) =>
{
  // Always respond 200
  res.status(200).send({ success: true });

  try
  {
    await addToQueue('article.sync', req.body.entityId);
  }
  catch (error)
  {
    // Log but don't crash
    await log(`Failed to queue article update: ${error.message}`, 'webhooks', 'ERROR');
  }
});