Error Codes¶

HTTP status codes¶

Status	Meaning
`200 OK`	Request succeeded
`202 Accepted`	Job created, processing started
`204 No Content`	Request succeeded, no body (e.g. DELETE)
`400 Bad Request`	Invalid input — check the `message` field
`401 Unauthorized`	Missing or invalid API token
`404 Not Found`	Resource not found
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server-side error

Error response format¶

All errors return a JSON body:

{ "error": "human-readable message" }

or

{ "message": "human-readable message", "status": "error" }

Common errors¶

400 — Invalid URL¶

{ "message": "URL must be an instagram.com link, got \"tiktok.com\"" }

Fix: Only Instagram URLs are supported. Use instagram.com/reel/... or instagram.com/p/....

400 — Missing URL¶

{ "message": "url is required" }

Fix: Include "url" in the request body.

401 — Invalid token¶

{ "error": "invalid API token" }

Fix: Check that your Authorization header is Bearer ist_your_token. Verify the token exists and hasn't been revoked in the dashboard.

401 — Missing token¶

{ "error": "API token required (Authorization: Bearer ist_...)" }

Fix: Add the Authorization: Bearer ... header.

404 — Job not found¶

{ "message": "not found", "status": "error" }

Fix: Check the job ID. IDs are integers returned by POST /api/v1/reels/analyze.

Job status: `error`¶

When a job's status is error, the error field contains the reason:

{
  "id": 42,
  "status": "error",
  "error": "Video is not available"
}

Common causes:

Cause	Fix
Video is private, deleted, or geo-blocked	Use a public Reel
Instagram temporarily rate-limited	Wait a few minutes and retry
AI could not process the video	Try again; report if persistent
Video format not supported	Rare; contact support
Storage error	Retry; contact support if persistent

Retry strategy¶

We recommend exponential backoff for transient errors:

import time
import httpx

def with_retry(fn, max_attempts=3, base_delay=1.0):
    for attempt in range(max_attempts):
        try:
            return fn()
        except httpx.HTTPStatusError as e:
            if e.response.status_code in (429, 500, 502, 503):
                if attempt < max_attempts - 1:
                    time.sleep(base_delay * (2 ** attempt))
                    continue
            raise