Error Handling

How to handle errors from the Influship API

Error Handling

All errors follow a consistent shape. Use the status code to decide what to do, and the error body for details.

Error response shape

Every error response returns this structure:

{
  "error": {
    "code": "error_code_here",
    "message": "Human-readable description",
    "status_code": 400
  }
}

The code field is a stable, machine-readable string. The message field is human-readable and may change between versions — don’t match against it programmatically.

Error code reference

Status	Code	Meaning	What to do
400	validation_error	Bad request body or params	Fix the request. Check required fields and types.
401	unauthorized	Missing or invalid API key	Check your X-API-Key header. See Authentication.
402	payment_required	Billing suspended — invoice unpaid	Fix billing in the dashboard, pay outstanding invoices.
404	not_found	Resource doesn’t exist	Check the ID or username.
429	rate_limit_exceeded	Over your per-minute or per-hour budget	Read Retry-After header or wait for the reset window. See Rate Limits.
500	internal_error	Something broke on the Influship side	Retry with backoff. If persistent, contact support.
503	service_unavailable	A live data upstream is temporarily unavailable	Retry after Retry-After if present, then back off with jitter.

Handling errors in code

SDK

import Influship, { APIError, RateLimitError } from 'influship';

const client = new Influship();

try {
  const results = await client.creators.search({
    query: 'fitness creators',
  });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Your Influship API key hit its account-level quota.
    const retryAfter = error.headers?.get('retry-after');
    console.log(`Rate limited. Retry after ${retryAfter}s`);
  } else if (error instanceof APIError && error.status === 503) {
    // Temporary upstream issue, often from a live scrape provider.
    const retryAfter = error.headers?.get('retry-after');
    console.log(`Service unavailable. Retry after ${retryAfter ?? 'a short backoff'}s`);
  } else if (error instanceof APIError) {
    console.log(`API error ${error.status}: ${error.message}`);
  } else {
    throw error;
  }
}

The SDK throws typed error classes, so you can catch specific error types and handle them differently. For raw HTTP, check the status code of the response.

Rate limit headers

Every response includes rate limit headers so you can track your budget before hitting 429. See Rate Limits & Tiers for the full header reference and trust tier table.

Implementation advice

For production integrations, handle 429 and retryable 503 responses with exponential backoff. A simple strategy: wait 2^attempt seconds, capped at 60 seconds, with jitter. If Retry-After is present, use it as the first delay.

Treat 429 as your API key’s account-level rate limit. Treat 503 service_unavailable from live data endpoints as a temporary upstream/platform issue, not as your quota being exhausted.

Treat 402 as a billing issue that needs human intervention — don’t retry it automatically. Surface it to your ops team or billing dashboard instead.