Envelope and errors
What every response looks like, every error code, and what to retry.
The envelope
{
"data": { "…": "…" },
"meta": { "count": 20, "limit": 20, "next_cursor": "…" },
"request_id": "req_01J…"
}data is one object, or an array on list endpoints. meta appears on lists. request_id is on every response, including errors.
Two headers travel with every billed response: X-Credits-Charged and X-Credits-Remaining. x-cache says hit or miss.
Errors
{
"error": {
"code": "not_found",
"message": "reel not found",
"hint": "…",
"request_id": "req_01J…"
}
}| Status | Code | When |
|---|---|---|
| 400 | invalid_url, invalid_handle, invalid_query | Missing or malformed url, handle or query |
| 400 | unsupported_platform_url | The URL is not an instagram.com URL |
| 400 | invalid_limit | limit is not an integer in range |
| 400 | upstream_spend_ceiling | The request would exceed the per-request cost ceiling; lower limit |
| 401 | missing_api_key, invalid_api_key | No key, or a wrong or revoked one |
| 402 | out_of_credits | Balance too low for the call |
| 402 | plan_required | A free key was refused by an endpoint’s per-call minimum; the message names the endpoint and the minimum, and a plan is the fix |
| 404 | not_found | Private, deleted, no transcript, or the URL resolves to nothing |
| 409 | job_not_ready | Job results requested before the job finished |
| 429 | rate_limited | Plan requests-per-minute exceeded |
| 500 | internal_error | Our side; safe to retry |
| 502 | upstream_failure | Transient fetch failure; safe to retry |
| 504 | upstream_timeout | The source took too long; safe to retry |
Retry 429 and 5xx with exponential backoff. Do not retry 400, 401, 402 or 404; the request itself needs to change.
import httpx, time
for attempt in range(5):
r = httpx.get(url, headers=headers, timeout=120)
if r.status_code == 429 or r.status_code >= 500:
time.sleep(2 ** attempt * 2)
continue
breakFailed calls are not charged. Empty results are free up to 25 a day per account; after that an empty result costs one credit.