Skip to content

error-handling.md

Latest commit

 

History

History
156 lines (115 loc) · 4.02 KB

error-handling.md

File metadata and controls

156 lines (115 loc) · 4.02 KB

Error Handling

igdb-wrapper uses a structured error hierarchy so you can handle failures precisely without parsing error messages.

Most application code should handle the errors users can recover from (IGDBNotFoundError, IGDBAuthError, and exhausted IGDBRateLimitError) and rethrow validation or unknown errors.

Error types

All errors extend IGDBError, which itself extends the native Error class.

Error
└── IGDBError
    ├── IGDBAuthError
    ├── IGDBRateLimitError
    ├── IGDBNotFoundError
    └── IGDBValidationError

IGDBError

Base class for all library errors. Catch this if you want to handle any IGDB-related failure in one place.

import { IGDBError } from "@api-wrappers/igdb-wrapper";

try {
  await client.games.findById(1);
} catch (err) {
  if (err instanceof IGDBError) {
    console.error("IGDB error:", err.message);
  }
}

For scripts, put client.dispose() in finally so cleanup still runs when a request fails:

const client = new IGDBClient(config);

try {
  await client.games.findById(1942);
} finally {
  await client.dispose();
}

IGDBAuthError

Thrown when the API returns a 401 Unauthorized response. This usually means your clientId or clientSecret is wrong, or your token has been revoked.

import { IGDBAuthError } from "@api-wrappers/igdb-wrapper";

if (err instanceof IGDBAuthError) {
  console.error("Authentication failed. Check your credentials");
}

IGDBRateLimitError

Thrown when the API returns a 429 Too Many Requests response. The retryAfterMs property contains the number of milliseconds to wait before retrying when the API sends a Retry-After header.

The built-in rate limiter and retry logic will handle most transient rate limit hits automatically. This error is only surfaced when all retry attempts are exhausted.

import { IGDBRateLimitError } from "@api-wrappers/igdb-wrapper";

if (err instanceof IGDBRateLimitError) {
  console.warn(`Rate limited. Retry after ${err.retryAfterMs}ms`);
}
Property Type Description
retryAfterMs number | undefined Milliseconds to wait before the next attempt, when provided

IGDBNotFoundError

Thrown by .firstOrThrow() and findById() when the query returns no results.

import { IGDBNotFoundError } from "@api-wrappers/igdb-wrapper";

if (err instanceof IGDBNotFoundError) {
  console.warn(`No results on endpoint: ${err.endpoint}`);
}
Property Type Description
endpoint string The endpoint that returned no results

IGDBValidationError

Thrown when you pass invalid arguments to the query builder. For example, a limit() value outside 1 to 500.

import { IGDBValidationError } from "@api-wrappers/igdb-wrapper";

if (err instanceof IGDBValidationError) {
  // Fix the query. This is a programming error, not a runtime one.
  console.error("Invalid query:", err.message);
}

Common causes:

  • limit(n) where n < 1 or n > 500
  • offset(n) where n < 0
  • paginate(n) where n < 1 or n > 500
  • Calling .count() on a manually constructed QueryBuilder without a count function

Recommended pattern

import {
  IGDBAuthError,
  IGDBNotFoundError,
  IGDBRateLimitError,
  IGDBValidationError,
} from "@api-wrappers/igdb-wrapper";

try {
  const game = await client.games.findById(9999999);
} catch (err) {
  if (err instanceof IGDBNotFoundError) {
    // Expected. Handle gracefully.
    console.log("Game not found");
  } else if (err instanceof IGDBAuthError) {
    // Likely a misconfiguration
    console.error("Bad credentials. Check environment variables");
    process.exit(1);
  } else if (err instanceof IGDBRateLimitError) {
    // Retries exhausted. Back off at the application level.
    console.warn(`Still rate limited after retries. Wait ${err.retryAfterMs}ms`);
  } else if (err instanceof IGDBValidationError) {
    // Programming error. Fix the query.
    throw err;
  } else {
    // Unknown error. Re-throw.
    throw err;
  }
}