# 11. Error Handling Strategy

### 11.1 Exception Hierarchy

```
TeamsPhoneError (base)
├── AuthenticationError (exit 2)
│   ├── TokenExpiredError
│   ├── InvalidCredentialsError
│   └── CertificateError
├── AuthorizationError (exit 3)
│   └── InsufficientPermissionsError
├── NotFoundError (exit 4)
│   ├── UserNotFoundError
│   ├── NumberNotFoundError
│   ├── LocationNotFoundError
│   └── TenantNotFoundError
├── ValidationError (exit 5)
│   ├── InvalidPhoneNumberError
│   ├── E911LocationRequiredError
│   ├── InvalidPolicyError
│   └── CsvValidationError
├── RateLimitError (exit 6)
├── ConfigurationError (exit 7)
│   ├── MissingConfigError
│   └── InvalidConfigError
└── ContractError (exit 8)
    └── SchemaValidationError
```

### 11.2 Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General/unexpected error |
| 2 | Authentication error |
| 3 | Authorization error |
| 4 | Not found |
| 5 | Validation error |
| 6 | Rate limit exceeded |
| 7 | Configuration error |
| 8 | Contract/schema error |

### 11.3 Retry Policy

| HTTP Status | Retry? | Strategy |
|-------------|--------|----------|
| 429 (Throttled) | Yes | Use `Retry-After` header, max 3 retries |
| 500, 502, 503, 504 | Yes | Exponential backoff: 1s, 2s, 4s |
| 401 (Unauthorized) | Once | Refresh token, retry once |
| 400, 403, 404 | No | Fail immediately with user message |

### 11.4 Error Message Format

All user-facing errors include remediation guidance:

```
✗ Error: Emergency location required for Calling Plan number +12065551234

Calling Plan numbers require an emergency location for E911 compliance.

To fix:
  1. Run 'locations list' to see available locations
  2. Re-run with: numbers assign john@contoso.com +12065551234 --location "Seattle-HQ"

Or set a default location in your tenant config:
  tenants update contoso --default-location "Seattle-HQ"
```

---

