Error Handling

1
import { TheholetruthApiError } from '@hole-foundation/sdk';
2
3
try {
4
  const results = await client.vectorSearch.search({
5
    query: 'FOIA exemptions'
6
  });
7
} catch (error) {
8
  if (error instanceof TheholetruthApiError) {
9
    console.error('API Error:', error.status);
10
    console.error('Code:', error.body.error.code);
11
    console.error('Message:', error.body.error.message);
12
13
    // Handle specific errors
14
    switch (error.body.error.code) {
15
      case 'AUTH_EXPIRED_TOKEN':
16
        // Refresh token
17
        break;
18
      case 'RATE_LIMIT_EXCEEDED':
19
        // Wait and retry
20
        const retryAfter = error.body.error.details.reset_at;
21
        break;
22
      case 'RESOURCE_NOT_FOUND':
23
        // Handle missing resource
24
        break;
25
      default:
26
        // Generic error handling
27
        break;
28
    }
29
  } else {
30
    // Network or other error
31
    console.error('Network error:', error);
32
  }
33
}

1
async function retryWithBackoff<T>(
2
  fn: () => Promise<T>,
3
  maxRetries = 3
4
): Promise<T> {
5
  for (let i = 0; i < maxRetries; i++) {
6
    try {
7
      return await fn();
8
    } catch (error) {
9
      if (error instanceof TheholetruthApiError) {
10
        // Don't retry client errors (4xx)
11
        if (error.status >= 400 && error.status < 500) {
12
          throw error;
13
        }
14
15
        // Retry server errors (5xx) with backoff
16
        if (i < maxRetries - 1) {
17
          const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
18
          await new Promise(resolve => setTimeout(resolve, delay));
19
          continue;
20
        }
21
      }
22
      throw error;
23
    }
24
  }
25
  throw new Error('Max retries exceeded');
26
}
27
28
// Usage
29
const results = await retryWithBackoff(() =>
30
  client.vectorSearch.search({ query: 'FOIA' })
31
);

1
async function handleRateLimit<T>(fn: () => Promise<T>): Promise<T> {
2
  try {
3
    return await fn();
4
  } catch (error) {
5
    if (
6
      error instanceof TheholetruthApiError &&
7
      error.body.error.code === 'RATE_LIMIT_EXCEEDED'
8
    ) {
9
      // Wait until reset time
10
      const resetAt = new Date(error.body.error.details.reset_at);
11
      const waitMs = resetAt.getTime() - Date.now();
12
13
      console.log(`Rate limited. Waiting ${waitMs}ms...`);
14
      await new Promise(resolve => setTimeout(resolve, waitMs));
15
16
      // Retry
17
      return await fn();
18
    }
19
    throw error;
20
  }
21
}
22
23
// Usage
24
const results = await handleRateLimit(() =>
25
  client.vectorSearch.search({ query: 'FOIA' })
26
);

1
// ❌ Missing token
2
const client = new HoleFoundationClient({
3
  environment: 'https://api.theholefoundation.org'
4
  // No token!
5
});
6
7
// ✅ Valid token
8
const client = new HoleFoundationClient({
9
  environment: 'https://api.theholefoundation.org',
10
  token: 'your-jwt-token'
11
});

1
// ❌ Missing required parameter
2
await client.vectorSearch.search({
3
  limit: 10
4
  // Missing 'query'!
5
});
6
7
// ✅ All required parameters
8
await client.vectorSearch.search({
9
  query: 'FOIA exemptions',
10
  limit: 10
11
});

1
// ❌ Non-existent resource
2
try {
3
  await client.vectorSearch.getDocument('invalid-id');
4
} catch (error) {
5
  if (
6
    error instanceof TheholetruthApiError &&
7
    error.body.error.code === 'RESOURCE_NOT_FOUND'
8
  ) {
9
    console.log('Document not found');
10
  }
11
}
12
13
// ✅ Check existence first
14
const results = await client.vectorSearch.search({
15
  query: 'document title'
16
});
17
18
if (results.results.length > 0) {
19
  const doc = await client.vectorSearch.getDocument(
20
    results.results[0].id
21
  );
22
}

1
try {
2
  await client.vectorSearch.search({ query: 'test' });
3
} catch (error) {
4
  if (error instanceof TheholetruthApiError) {
5
    console.log('Request ID:', error.body.error.request_id);
6
    // Report this ID to support
7
  }
8
}

1
const client = new HoleFoundationClient({
2
  environment: 'https://api.theholefoundation.org',
3
  token: 'your-jwt-token',
4
  // Add request/response logging
5
  httpx_client: httpx.Client({
6
    event_hooks: {
7
      request: [req => console.log('Request:', req)],
8
      response: [res => console.log('Response:', res)]
9
    }
10
  })
11
});

1
// ❌ No error handling
2
const results = await client.vectorSearch.search({ query: 'FOIA' });
3
4
// ✅ Proper error handling
5
try {
6
  const results = await client.vectorSearch.search({ query: 'FOIA' });
7
} catch (error) {
8
  // Handle error appropriately
9
  console.error('Search failed:', error);
10
}

1
// ✅ Validate input
2
function validateSearchQuery(query: string): void {
3
  if (!query || query.trim().length === 0) {
4
    throw new Error('Query cannot be empty');
5
  }
6
  if (query.length > 1000) {
7
    throw new Error('Query too long (max 1000 characters)');
8
  }
9
}
10
11
try {
12
  validateSearchQuery(userInput);
13
  const results = await client.vectorSearch.search({
14
    query: userInput
15
  });
16
} catch (error) {
17
  // Caught validation error before API call
18
}

1
// ❌ Generic error
2
catch (error) {
3
  alert('Error!');
4
}
5
6
// ✅ User-friendly, specific messages
7
catch (error) {
8
  if (error instanceof TheholetruthApiError) {
9
    switch (error.body.error.code) {
10
      case 'AUTH_EXPIRED_TOKEN':
11
        alert('Your session has expired. Please log in again.');
12
        break;
13
      case 'RATE_LIMIT_EXCEEDED':
14
        alert('Too many requests. Please wait a moment and try again.');
15
        break;
16
      default:
17
        alert(`Error: ${error.body.error.message}`);
18
    }
19
  }
20
}