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

# Errors

> Error codes and how to handle them

## Error format

All errors follow a consistent JSON structure:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}
```

## Error codes

| Code                   | HTTP Status | Description                                         | Retryable |
| ---------------------- | ----------- | --------------------------------------------------- | --------- |
| `UNAUTHORIZED`         | 401         | Missing or invalid API key                          | No        |
| `INSUFFICIENT_CREDITS` | 402         | Not enough credits for this endpoint                | No        |
| `INVALID_PARAM`        | 400         | Missing or invalid query parameter                  | No        |
| `RATE_LIMITED`         | 429         | Too many requests — slow down                       | Yes       |
| `SCRAPE_FAILED`        | 502         | The scraping job failed after retries               | Yes       |
| `TIMEOUT`              | 504         | The scraping job did not complete within 30 seconds | Yes       |
| `INTERNAL_ERROR`       | 500         | Unexpected server error                             | Yes       |

## Handling errors

### 401 — Unauthorized

Check that you're sending the `x-api-key` header and that your key is valid and active.

```bash theme={null}
# Wrong
curl https://api.scraper.creatorlookup.com/v1/credit-balance

# Correct
curl -H "x-api-key: sk-your-api-key" \
  https://api.scraper.creatorlookup.com/v1/credit-balance
```

### 402 — Insufficient Credits

Your API key doesn't have enough credits. Check your balance and request a top-up.

### 429 — Rate Limited

You've exceeded your per-minute request limit. Wait and retry with exponential backoff. See [Rate Limits](/rate-limits) for details.

### 502 — Scrape Failed

The scraping job failed. This can happen when:

* The target profile/post doesn't exist or is private
* Instagram is temporarily blocking requests
* The target content has been removed

Retry after a short delay. If the error persists, the content may not be accessible.

### 504 — Timeout

The scraping job didn't complete within 30 seconds. This typically happens during high load. Retry the request — subsequent attempts often succeed due to caching from partial progress.

## Example: error handling

<CodeGroup>
  ```javascript JavaScript theme={null}
  const res = await fetch(
    "https://api.scraper.creatorlookup.com/v1/instagram/profile?username=example",
    { headers: { "x-api-key": "sk-your-api-key" } }
  );

  if (!res.ok) {
    const { error } = await res.json();

    switch (error.code) {
      case "RATE_LIMITED":
        // Wait and retry
        break;
      case "INSUFFICIENT_CREDITS":
        // Alert user to top up
        break;
      case "SCRAPE_FAILED":
      case "TIMEOUT":
        // Retry with backoff
        break;
      default:
        console.error(`API error: ${error.code} — ${error.message}`);
    }
  }
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.scraper.creatorlookup.com/v1/instagram/profile",
      params={"username": "example"},
      headers={"x-api-key": "sk-your-api-key"},
  )

  if not res.ok:
      error = res.json()["error"]

      if error["code"] == "RATE_LIMITED":
          pass  # Wait and retry
      elif error["code"] == "INSUFFICIENT_CREDITS":
          pass  # Alert user to top up
      elif error["code"] in ("SCRAPE_FAILED", "TIMEOUT"):
          pass  # Retry with backoff
      else:
          print(f"API error: {error['code']} — {error['message']}")
  ```
</CodeGroup>