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.

Optional fields inside error provide more context: param identifies an invalid parameter, and details contains structured error information. Read the HTTP response status even when error.status_code is absent.

Save the X-Request-Id response header when reporting a failed request to support. error.request_id is optional; your client should not require a request ID or timestamp in the JSON body.

Most authenticated 402 responses use payment_required and also include a reason_code and next_step. Branch on code first. For payment_required, then branch on reason_code when deciding which recovery action to show. Search can instead return insufficient_credits when remaining credits cannot cover the request; that body does not include reason_code or next_step.

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.
402	insufficient_credits	Remaining credits cannot cover this request	Add a payment method, then retry. Do not retry automatically.
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.
404	seed_not_found	A lookalike seed is not available for similarity matching	Choose another seed. Retrying the same seed does not change the result.
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.
502	upstream_contract_broken	The API could not process the source data	Don’t retry automatically. Fall back to cached data and contact support if it persists.
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 && error.status === 502) {
    // Source data could not be processed; do not retry automatically.
    console.log('Upstream data unusable. Do not retry; use cached data instead.');
  } 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 temporary unavailability, not as your quota being exhausted. Honor Retry-After when present, including for Instagram post and transcript lookups.

For lookalike requests, treat 404 seed_not_found as a seed-level result rather than a temporary outage. Select another seed; don’t retry the same request with backoff.

Do not fold 502 upstream_contract_broken into your 503 retry path. A 503 indicates temporary unavailability; honor Retry-After when present and use bounded backoff. A 502 upstream_contract_broken means the API could not process the source data. Do not retry automatically; use your last cached value and contact support if the issue persists. Retrying an already-settled x402 or MPP request requires another payment.

Treat 402 as a billing issue that needs human intervention. Do not retry it automatically. Surface payment_required to your ops team or billing dashboard, and treat insufficient_credits as a prompt to add a payment method. Temporary failures while checking billing state return retryable 503 responses instead.