Skip to main content

​
Error format

All errors follow a consistent JSON structure: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

​
Error codes

CodeHTTP StatusDescriptionRetryable
UNAUTHORIZED401Missing or invalid API keyNo
INSUFFICIENT_CREDITS402Not enough credits for this endpointNo
INVALID_PARAM400Missing or invalid query parameterNo
RATE_LIMITED429Too many requests — slow downYes
SCRAPE_FAILED502The scraping job failed after retriesYes
TIMEOUT504The scraping job did not complete within 30 secondsYes
INTERNAL_ERROR500Unexpected server errorYes

​
Handling errors

​
401 — Unauthorized

Check that you’re sending the x-api-key header and that your key is valid and active. 
# 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 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

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}`);
  }
}