> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reach.raysium.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Circuit breakers

# Circuit Breakers

Circuit breakers protect your Telegram accounts from blocks by automatically pausing campaigns when issues are detected.

## Overview

The circuit breaker system monitors your Telegram accounts for signs of detection and automatically pauses campaigns to prevent further damage.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/raysium/security/placeholder-circuit-breaker.png" alt="Circuit Breaker Dashboard" />

## How Circuit Breakers Work

### Detection Triggers

The system monitors for these issues:

| Issue         | Description                       | Severity |
| ------------- | --------------------------------- | -------- |
| FloodWait     | Telegram rate limit exceeded      | High     |
| PeerFlood     | Too many messages to non-contacts | High     |
| Smart Block   | Hidden restriction by Telegram    | Medium   |
| Privacy Error | Cannot message user               | Low      |
| Auth Error    | Authentication issues             | High     |

### Automatic Response

When issues are detected:

1. **Detection**: System identifies the issue type
2. **Pause**: All campaigns using that account pause
3. **Notify**: User is alerted to the issue
4. **Wait**: System tracks required wait time
5. **Resume**: User manually resumes when safe

## Error Types

### FloodWait

**What it means**: Telegram has rate-limited the account

**Causes**:

* Too many messages sent quickly
* Exceeded daily message limits
* Violated Telegram terms

**Response**:

* Minimum 48-hour lockout
* Additional wait time based on severity
* Account health score reduced

### PeerFlood

**What it means**: Account sent too many messages to users who haven't saved the contact

**Causes**:

* Messaging too many new contacts
* Low response rate
* Spam-like behavior detected

**Response**:

* All active campaigns pause immediately
* Minimum 48-hour cooldown
* Requires manual review before resume

### Smart Block

**What it means**: Telegram has silently restricted the account

**Causes**:

* Suspicious activity patterns
* User reports
* Automated behavior detection

**Response**:

* Account marked as warning status
* Reduced daily limits
* Health score capped at 60%

### Privacy Error

**What it means**: Cannot send messages to specific user

**Causes**:

* User privacy settings
* User blocked the account
* User hasn't saved contact

**Response**:

* Skip that lead
* Continue with other leads
* Log error for review

## Account Health Score

### Score Calculation

Health score (0-100%) based on:

| Factor            | Weight        |
| ----------------- | ------------- |
| FloodWait count   | -10% each     |
| PeerFlood count   | -15% each     |
| Smart Block count | -20% each     |
| Error rate        | -5% per error |
| Recent activity   | +10% positive |

### Health Status

| Score   | Status   | Action              |
| ------- | -------- | ------------------- |
| 80-100% | Healthy  | Normal operation    |
| 60-79%  | Warning  | Monitor closely     |
| 40-59%  | Critical | Reduce activity     |
| 0-39%   | Blocked  | Manual intervention |

<img src="https://mintlify.s3.us-west-1.amazonaws.com/raysium/security/placeholder-health-score.png" alt="Health Score Display" />

## Circuit Breaker Configuration

### Per-Account Settings

Configure error handling per account:

#### FloodWait Pause Duration

| Value | Behavior                         |
| ----- | -------------------------------- |
| 0     | Use Telegram's wait time         |
| 1-24  | Hours of additional pause        |
| -1    | Indefinite (manual intervention) |

#### Auth/PeerFlood Pause Duration

| Value | Behavior                         |
| ----- | -------------------------------- |
| 0     | No additional pause              |
| 24-72 | Hours of pause                   |
| -1    | Indefinite (manual intervention) |

#### High Error Threshold

* Default: 10 errors in 24 hours
* Auto-pause: Toggle to pause account when threshold reached

## Manual Control

### Clearing Rate Limits

Manually clear rate limit status:

```http theme={null}
POST /telegram-security/clear-rate-limit/{account_id}
```

### Checking Resume Eligibility

Check if campaign can resume:

```http theme={null}
GET /telegram-security/can-resume-campaign/{campaign_id}
```

Returns:

* `can_resume`: boolean
* `block_reason`: string (if blocked)
* `account_status`: current status

### Manual Resume

Resume campaigns after issues resolved:

1. Navigate to Telegram Security
2. Find affected account
3. Click **Reactivate**
4. Confirm resume

## Best Practices

1. **Proactive Warming**: Always warm up new accounts
2. **Rate Limit Profiles**: Use appropriate profiles for account age
3. **Monitor Health**: Regularly check account health scores
4. **Respond Quickly**: Address issues when detected
5. **Patience**: Wait full cooldown period before resuming
6. **Reduce Activity**: Lower limits after any block

## Counter Reset Times

### Daily Limits

* **Reset Time**: Midnight UTC
* **Applies to**: Daily message counters

### Hourly Limits

* **Reset Time**: Start of every hour
* **Applies to**: Hourly rate limits

## Troubleshooting

### Account Blocked Indefinitely

If account shows indefinite block:

1. Do not try to use the account
2. Wait 7 days minimum
3. Try small test messages
4. Gradually increase activity
5. Consider account replacement

### Frequent FloodWaits

If experiencing frequent FloodWaits:

1. Lower rate limit profile
2. Increase delays between messages
3. Check for automation issues
4. Review message content
5. Consider warming up account

### PeerFlood Loop

If stuck in PeerFlood cycle:

1. Pause all campaigns immediately
2. Wait minimum 72 hours
3. Review lead quality
4. Improve targeting
5. Resume with lower limits