Configuring Bitrix24 integration error handling

Setting Up Error Handling for Bitrix24 Integrations

An integration that fails silently is worse than no integration at all. The manager thinks the request went to storage, but it's stuck in a queue with an authorization error three days old. Proper error handling isn't about pretty messages—it's a system that knows about problems before the customer complains.

Typology of Errors in Bitrix24 Integrations

Bitrix24 API errors. Response codes: 200 with error field in body (logical error), 401 (token expired), 429 (rate limit exceeded), 503 (service temporarily unavailable). Each type requires its own response.

External system errors. Logistics returns 400 Bad Request (invalid address), banking API returns 422 Unprocessable Entity (INN not found). These are business errors requiring employee attention, not automatic retry.

Data transformation errors. Mapping data from Bitrix24 to external system format—required field is empty. Or data type mismatch. Such errors occur when structure changes in one of the systems.

Network errors. Connection timeout, DNS unresolved, SSL error. Usually temporary, suitable for automatic retry.

Error Handling Structure

For each integration flow, define three things: what counts as an error, how to respond, who to notify.

Logging. Every request to external system and its response is logged. Minimum set: timestamp, method, input data (with sensitive field masking), response status, error body, execution time. In Bitrix24, use built-in \Bitrix\Main\Diag\Debug::writeToFile() or external stack (Monolog → ELK).

Error classification. In the error handler, determine which class the problem belongs to:

switch (true) {
    case $e instanceof RateLimitException:
        // Wait and retry
        $this->scheduleRetry($job, delay: 60);
        break;
    case $e instanceof AuthException:
        // Refresh token and retry
        $this->refreshToken();
        $this->scheduleRetry($job, delay: 5);
        break;
    case $e instanceof ValidationException:
        // This is a business error—notify manager
        $this->notifyManager($job, $e->getMessage());
        $this->markFailed($job);
        break;
    case $e instanceof NetworkException:
        // Temporary issue—retry with exponential backoff
        $this->scheduleRetry($job, delay: $job->getBackoffDelay());
        break;
}

Notifications. Business errors (data failed validation, counterparty not found)—notify responsible manager via im.notify.system.add in Bitrix24. System errors (service unavailable, authorization error)—notify technical staff via Telegram bot or email.

Error Dashboard

Integration support requires an interface for viewing failed operations. Implemented as a Bitrix24 embedded app or separate admin interface. Shows:

• List of stuck operations with error description
• Ability to manually retry operation
• History of attempts with external system responses

Alternative: error table in custom infoblock or Bitrix24 smart process—then responsible person sees errors directly in CRM without separate interface.

Monitoring and Alerts

Error handling setup is 20% of code that saves 80% of headaches in production. Systems without error handling require manual intervention at every problem and accumulate "lost" operations that failed without notifying anyone.