> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/x402) and [MPP](/guides/mpp) guides.

## Error response shape

Authenticated API errors return this structure:

```json theme={null}
{
  "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](/guides/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](/concepts/quotas-and-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

<CodeGroup>
  ```typescript SDK theme={null}
  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;
    }
  }
  ```

  ```bash cURL theme={null}
  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}'
  ```
</CodeGroup>

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](/concepts/quotas-and-limits) 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.