Errors & limits
Status codes
| Code | Meaning | What to do |
|---|---|---|
400 | URL belongs to another platform, or is malformed | Check the input |
401 | Key missing, unknown or revoked | See authentication |
404 | Post not found, private, or removed | Do not retry |
429 | Monthly quota used up, or too many requests per second | Wait for the reset, or move up a plan |
502 | Resolver temporarily unavailable | Retry once after a second or two |
Retrying
Only 502 is worth retrying automatically. A 404 means the post is gone at the source — retrying it just spends quota on something that will never resolve.
res = call_api(url)
if res.status_code == 502: # transient — one retry clears most of them
time.sleep(1.5)
res = call_api(url)
if res.status_code == 404: # the post is gone; retrying only burns quota
skip(url)Error format
{ "detail": "Post not found, private, or removed" }Monthly quotas
| Plan | Requests / month | Price |
|---|---|---|
| Free | 500 | $0 |
| Mini | 5,000 | $1.99 |
| Starter | 10,000 | $2.99 |
| Plus | 15,000 | $3.99 |
| Pro | 20,000 | $4.99 |
| Business | 35,000 | $6.99 |
| Scale | 50,000 | $8.49 |
Counters reset on the 1st of each month. A carousel of ten files counts once — quota is measured in calls, not files.
Rate limits
| Plan | Per second | Per hour |
|---|---|---|
| Free | 1 | 500 |
| Mini | 2 | 1,500 |
| Starter | 3 | 2,500 |
| Plus | 4 | 3,500 |
| Pro | 5 | 4,500 |
| Business | 8 | 7,000 |
| Scale | 10 | 9,000 |
Two different ceilings answer with 429. A burst that is merely too fast carries a Retry-After header and clears within the second; a spent monthly quota does not, and waits for the 1st. Read the header to tell them apart.
A call refused by either ceiling costs nothing — it never reaches your monthly counter.
Your live usage is on the dashboard.