AbuseIPDB Node.js Client

Common errors

• TypeError: AbuseIPDBClient is not a constructor

  cause Attempting to instantiate the `AbuseIPDBClient` class incorrectly in a CommonJS environment or with an incorrect ESM import.
  fix For CommonJS, use `const { AbuseIPDBClient } = require('abuseipdb-client');`. For ESM, ensure `import { AbuseIPDBClient } from 'abuseipdb-client';` is used (named import).

• Error: Response code 401 (Unauthorized) - Missing API Key or invalid API Key.

  cause The AbuseIPDB API key was either not provided to the client constructor or is incorrect/expired.
  fix Ensure you pass a valid AbuseIPDB API key string when initializing `new AbuseIPDBClient(yourApiKey)` and that the key is active and has necessary permissions.

• { errors: [ { detail: 'ipAddress must be a valid IPv4 or IPv6 address', status: 422, source: { parameter: 'ipAddress' } } ] }

  cause An invalid IP address string was provided to an API method (e.g., `client.check()`). The API's runtime validation (via Zod) caught the malformed input.
  fix Always validate IP address inputs in your application code before passing them to `abuseipdb-client` methods to ensure they conform to IPv4 or IPv6 standards.

Warnings

• breaking The library explicitly requires Node.js version 24 or higher due to its `engines` field configuration. Using it with older Node.js versions will result in errors.
  Fix: Ensure your Node.js environment is upgraded to version 24 or higher. Alternatively, use an older version of the library that supports your Node.js version, if available.
• gotcha API keys should never be hardcoded directly into your source code. They must be managed securely, typically via environment variables.
  Fix: Store your AbuseIPDB API key in an environment variable (e.g., `ABUSEIPDB_API_KEY` in a `.env` file) and access it using `process.env.ABUSEIPDB_API_KEY`.
• gotcha The client wraps all API responses into a consistent object structure, distinguishing between `result` and `error` properties. It does not throw exceptions for API-level errors (e.g., invalid input, unauthorized access); instead, it populates the `error` object.
  Fix: Always check the `error` property of the response object after any API call. If `error` is defined, it contains details about the API-specific issue, and `result` will be undefined. Handle these errors explicitly.
• gotcha AbuseIPDB enforces rate limits. The client exposes rate limit information in the `headers` object of the response (e.g., `x-ratelimit-limit`, `x-ratelimit-remaining`, `retry-after`). Exceeding limits will lead to errors.
  Fix: Implement a robust rate-limiting strategy in your application. Monitor the `x-ratelimit-remaining` header and respect the `retry-after` header if present to avoid being temporarily blocked.

Install

• npm install abuseipdb-client npm
• yarn add abuseipdb-client yarn
• pnpm add abuseipdb-client pnpm

Imports

• AbuseIPDBClient
  wrong:

  const AbuseIPDBClient = require('abuseipdb-client');

  correct:

  import { AbuseIPDBClient } from 'abuseipdb-client';

  The primary class for interacting with the AbuseIPDB API. It is a named export. While CJS is supported, ESM is recommended for modern Node.js applications.
• AbuseIPDBClient
  wrong:

  import AbuseIPDBClient from 'abuseipdb-client';

  correct:

  const { AbuseIPDBClient } = require('abuseipdb-client');

  Correct CommonJS import for the named export. Direct default import will fail as there is no default export.
• AbuseIPDBResponse

  import type { AbuseIPDBResponse } from 'abuseipdb-client';

  Type import for the structured response object returned by client methods.

Quickstart

This quickstart demonstrates initializing the `AbuseIPDBClient` with an API key from environment variables and performing an IP check, including structured error handling.

import { AbuseIPDBClient } from 'abuseipdb-client';
import 'dotenv/config'; // Ensure environment variables are loaded if using .env

const API_KEY = process.env.ABUSEIPDB_API_KEY ?? '';

if (!API_KEY) {
  console.error('ABUSEIPDB_API_KEY environment variable is not set.');
  process.exit(1);
}

const client = new AbuseIPDBClient(API_KEY);

async function checkIp() {
  try {
    const response = await client.check('127.0.0.1', { maxAgeInDays: 15 });

    const { headers, result, error } = response;

    console.log('API Headers:', headers);

    if (error) {
      console.error('API Error:', error);
    } else if (result) {
      console.log('API Result:', result.data);
    }
  } catch (err) {
    console.error('Client execution error:', err);
  }
}

checkIp();