Error Handling

How to handle errors from the Influship API

Error Handling

Authenticated API errors use a consistent JSON shape. Use the HTTP status code to decide what to do, and the error body for details. Unauthenticated x402 and MPP payment challenges carry their details in response headers; see the x402 and MPP guides.

Error response shape

Authenticated API errors return this structure:

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

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	Account billing requires attention	Open the billing dashboard and follow the supplied next step.
404	not_found	Resource doesn’t exist. For live/raw profile scrapes, the account is missing, deleted, or returns no public data	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.search.create({
    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 issue while fetching fresh live data.
    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;
  }
}

curl -w "\n%{http_code}\n" \
  -X POST https://api.influship.com/v1/search \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"query": "fitness creators", "limit": 10}'

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. Some upstream platforms return soft-block payloads inside otherwise successful responses; Influship normalizes those into retryable 503 responses with Retry-After when possible — including the raw Instagram post and transcript lookups.

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.