Rate Limits and Abuse Prevention Contract (CAIRL-Specific)
Status: Canonical Last Updated: 2026-02-06 Owner: Engineering
Purpose
This document defines the rate limiting, abuse prevention, and enforcement rules for CAIRL.
It establishes:
- Hard limits on user and partner actions
- Abuse detection and mitigation strategies
- Infrastructure safety constraints
- Enforcement precedence rules
- The relationship between safety, billing, and user intent
This document defines system-wide invariants. All features, specs, and flows MUST comply.
Scope
This contract applies to:
- All user-facing actions
- All API endpoints (public and internal)
- All background jobs and cron tasks
- All third-party provider integrations
- All messaging, communication, phone, and partner systems
No feature may weaken or bypass these rules.
Core Abuse-Prevention Principles (Invariants)
- Safety and platform integrity override user intent.
- Rate limits are enforced server-side only.
- UI gating is advisory and non-authoritative.
- Abuse prevention rules are explicit, layered, and auditable.
- Enforcement is progressive where possible and absolute where required.
- Billing tier does not exempt users from abuse controls.
Abuse Categories
The system recognizes the following abuse classes:
Volume Abuse
- Excessive requests
- Flooding actions
- Resource exhaustion attempts
Behavioral Abuse
- Repeated prohibited actions
- Attempted bypass of controls
- Patterned misuse
Content Abuse
- Spam-like content
- Repetitive or templated payloads
- Malicious or deceptive behavior
Partner / Provider Abuse
- Actions that risk provider reputation
- Violation of provider terms
- Excessive webhook or API usage
Rate Limiting Layers
Rate limiting MUST be applied at multiple layers.
Application-Level Limits
- Enforced per user, per route, or per action
- Applied in server-side logic
Resource-Level Limits
- Applied to constrained or reputation-sensitive resources
- Prevents exhaustion regardless of tier
Provider-Imposed Limits
- Inherited from providers (Stripe, Twilio, SES, etc.)
- Internal limits SHOULD be stricter than provider limits
- Provider throttling MUST trigger protective backoff
Email Forwarding (Hard Stop — Infrastructure Safety Limit)
Email forwarding caps are platform safety limits, not billing limits.
| Tier | Daily Cap |
|---|---|
| CAIRL 0 | 30 |
| CAIRL 300 | 60 |
| CAIRL 600 | 120 |
| CAIRL 1200 | 240 |
| CAIRL 2400 | 480 |
| CAIRL 4800 | 960 |
| CAIRL 9600 | 1,920 |
Rules:
- Forwarding pauses at cap until the next calendar day (UTC)
- Email forwarding is NOT eligible for overage billing
- Upgrading tier is the only way to increase the cap
- This limit applies regardless of credits or account balance
Rationale: Sender reputation is shared infrastructure. One user’s abuse degrades deliverability for all users. This justifies a hard stop rather than an overage or soft-limit model.
Phone System Guardrails (Fraud Prevention)
Phone features are subject to fraud prevention controls regardless of tier.
| Guardrail | Rule |
|---|---|
| International calls/SMS | Blocked |
| Premium rate numbers | Blocked |
| Max concurrent calls | 5 per user |
| Voicemail length | 2 minutes max |
| Geography | US only at launch |
| Number release | After 60 days inactive with zero credits |
Rules:
- Guardrails apply to all tiers, including CAIRL 9600
- Enforced at the Twilio integration layer
- Violations are logged but not user-visible
- No overage, upgrade, or admin override bypasses these limits
Partner API Rate Limits and Guardrails (B2B)
VAE Deduplication
| Parameter | Value |
|---|---|
| Window | 2 minutes |
| Key | partner_id + user_id + check_type |
| Behavior | Identical checks count as 1 VAE |
Purpose: Prevents overbilling due to retries, integration bugs, or frontend issues.
VAE Guardrail Trigger
| Condition | Response |
|---|---|
| Same partner + user + check >10 times in 5 minutes | Guardrail activates |
Guardrail behavior:
- VAE counting is frozen for that combination for 15 minutes
- Eligibility responses continue
- Partner receives warning:
"vae_counted": false - All triggers are logged for admin review
Rationale: CAIRL does not monetize partner mistakes. Guardrails surface issues early without breaking partner integrations.
Test Mode Limits
| Key Type | Rate Limit |
|---|---|
cairl_test_* |
100 calls/day per partner |
Test mode rules:
- No calls to AWS Rekognition
- No VAEs counted
- No real user records created
- All calls logged to partner dashboard
CAIRL 0 (Free Trial) Specific Limits
Free trial accounts have additional constraints.
| Resource | CAIRL 0 Limit | Paid Tier Behavior |
|---|---|---|
| Duration | 30 days | Unlimited |
| Identities | 1 | Tier-based |
| Proxy emails | 1 (receive-only) | Tier-based |
| Phone | None | Tier-based |
| Document certifications | 0 | Tier-based |
| Partner site access | Not available | Available |
Auto-deletion policy:
- 60 days of inactivity triggers permanent deletion
- Warning at 45 days
- Warning at 55 days
These limits are not bypassable.
Billing and Tier Interaction
- Billing tier determines capacity, not permission
- Higher tiers receive higher allocations
- No tier is exempt from abuse enforcement
- Credits or quotas MUST NOT go negative
Overage Eligibility
| Resource | Overage Eligible | Reason |
|---|---|---|
| Extra accounts | Yes | User opt-in |
| Extra storage | Yes | User opt-in |
| Document certifications | Yes | User opt-in |
| Phone credits | Yes | User opt-in |
| Email forwarding | No | Infrastructure protection |
If billing limits and abuse limits conflict, the stricter rule applies.
If safety limits and billing limits conflict, safety wins.
Enforcement Actions
The system MAY apply:
- Throttling
- Rejection with explanation
- Cooldowns
- Feature suspension
- Account-level restriction
- Administrative review
Enforcement SHOULD be progressive unless immediate risk exists.
Enforcement Precedence
If multiple enforcement rules apply simultaneously, precedence is:
- Legal / compliance enforcement
- Safety and abuse prevention
- Provider suppression or throttling
- Billing or quota limits
- UI or UX guidance
CAIRL Examples
| Scenario | Result |
|---|---|
| Email cap hit with overage enabled | Hard stop |
| Partner VAE guardrail hit | Counting frozen |
| HIPAA deletion requested | Retention enforced |
| Premium phone number attempted | Blocked |
| Storage exceeded with overage | Overage billed |
Higher precedence rules override lower ones without exception.
Logging and Observability
The system MUST log:
- Rate limit violations
- Guardrail activations
- Enforcement actions
- Suspensions and restorations
CAIRL-Specific Logging Requirements
| Event Type | Retention | Access |
|---|---|---|
| Email forwarding cap hits | 30 days | Admin |
| Phone guardrail blocks | 30 days | Admin |
| Partner VAE guardrails | 30 days | Admin + Partner |
| Partner deduplication events | 30 days | Partner |
| CAIRL 0 deletion warnings | 90 days | Admin |
| Account suspension/restoration | 1 year | Admin |
Guardrail logs are not user-visible.
Non-Negotiable Rules
- Abuse controls cannot be bypassed.
- Rate limits are server-enforced.
- Provider safety rules are respected.
- Infrastructure safety overrides billing.
- No feature may weaken these guarantees.
References
docs/governance/doc-authority.new.mddocs/contracts/authz-and-roles.new.mddocs/contracts/data-retention.new.mddocs/specs/CAIRL_User_Pricing_Service_Tiers_v2.1.mddocs/specs/CAIRL_Partner_B2B_Billing_Spec_v2.4.mddocs/flows/CAIRL_User_Flow_6_Document_Storage_Certification.md- Provider terms (Stripe, Twilio, AWS SES)
End of Document