linear-common-errors

# Linear Common Errors

## Overview
Quick reference for diagnosing and resolving common Linear API errors.

## Prerequisites
- Linear SDK or API access configured
- Access to application logs
- Understanding of HTTP status codes

## Error Categories

### Authentication Errors (401/403)

#### Invalid API Key
```
Error: Authentication required
Code: UNAUTHENTICATED
```

**Causes:**
- API key is invalid, expired, or revoked
- Key format is incorrect (should start with `lin_api_`)
- Environment variable not loaded

**Solutions:**
```typescript
// Verify key format
const apiKey = process.env.LINEAR_API_KEY;
if (!apiKey?.startsWith("lin_api_")) {
  console.error("Invalid API key format");
}

// Test authentication
const client = new LinearClient({ apiKey });
try {
  await client.viewer;
  console.log("Authentication successful");
} catch (e) {
  console.error("Authentication failed:", e);
}
```

#### Permission Denied
```
Error: You don't have permission to access this resource
Code: FORBIDDEN
```

**Causes:**
- API key doesn't have required scope
- User not a member of the team/organization
- Resource belongs to different workspace

**Solutions:**
- Check API key permissions in Linear Settings > API
- Verify team membership
- Regenerate key with correct permissions

### Rate Limiting Errors (429)

```
Error: Rate limit exceeded
Code: RATE_LIMITED
Headers: X-RateLimit-Remaining: 0, Retry-After: 60
```

**Causes:**
- Too many requests in time window
- Burst of requests without throttling

**Solutions:**
```typescript
// Implement exponential backoff
async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error: any) {
      if (error?.extensions?.code === "RATE_LIMITED" && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000;
        console.log(`Rate limited, retrying in ${delay}ms...`);
        await new Promise(r => setTimeout(r, delay));