# Anti-flooding system

The anti-flooding system prevents sending an excessive number of messages to the same destination phone number. It protects end users from unwanted message floods and ensures compliance with carrier policies.

The two mechanisms behave differently: mechanism 1 silently drops the message (returns HTTP `200 OK`), while mechanism 2 returns error code `60`.

## Mechanisms

There are two independent mechanisms, both applied per destination phone number.

### Mechanism 1 — Duplicate content rate limit

Blocks messages with the same content sent to the same number via the same provider.

- **Limit**: max 2 messages per provider
- **Time window**: 1 hour
- **Content matching**: the message text is not stored — only its hash is computed and compared (for privacy reasons)
- **API response**: HTTP `200 OK` — the message is silently dropped, no error is returned


### Mechanism 2 — Total volume rate limit

Blocks any message sent to the same number regardless of content.

- **Limit**: max 150 messages
- **Time window**: 1 hour
- **API response**: HTTP `500 {"code": 60, "message": "Anti-flooding error"}`


If more than 150 messages are sent to the same destination number within 1 hour, subsequent attempts are blocked until the time window resets.

## Sequence diagram

```mermaid
sequenceDiagram
    participant App as Your Application
    participant GW as SMS Gateway
    participant P as Provider

    Note over App,P: Mechanism 1 — Duplicate content (same hash, same provider, within 1 hour)
    App->>GW: POST /send (same message, 3rd attempt)
    GW-->>App: HTTP 200 OK
    Note right of GW: Message silently dropped,<br/>not forwarded to provider

    Note over App,P: Mechanism 2 — Volume limit (>150 messages in 1 hour)
    App->>GW: POST /send (101st message)
    GW-->>App: HTTP 500 {"code": 60, "message": "Anti-flooding error"}
    Note right of GW: Message blocked,<br/>error returned
```

## Error response

Only mechanism 2 returns an error. The send API returns:

```json
{
  "code": 60,
  "message": "Anti-flooding error",
  "details": null
}
```

## Notes

- The two mechanisms are independent
- Only mechanism 2 returns error code `60`; mechanism 1 silently drops the message
- Limits apply per destination phone number, not per sender account
- There is no way to bypass or reset the limits — wait for the time window to expire