Skip to main content

Error format

All errors follow a consistent JSON structure:

Error codes

Handling errors

401 — Unauthorized

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

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