API reference
Errors & rate limits
Error format
Every error response has the same shape:
{ "error": { "code": "rate_limited", "message": "Too many requests. Limit: 100/min." } }
| HTTP | Code | Meaning | Fix |
|---|---|---|---|
| 400 | missing_fields | Required body/query params absent. | Check the endpoint reference. |
| 400 | invalid_fields | Field validation failed (e.g. bad platform, script too long, duration out of range). | Check the endpoint reference for constraints. |
| 400 | invalid_creator | The creator_id doesn't match any creator. | Use GET /api/v1/creators to list available creators. |
| 400 | invalid_url | Webhook url failed validation (must be an https:// endpoint). | Check the URL and re-register. |
| 400 | invalid_events | Webhook events must be a non-empty subset of stream.started, stream.ended, stream.error. | Fix the event list. |
| 401 | unauthorized | Key missing, malformed, or revoked. | Verify the Bearer tt_… header; create a new key if revoked. |
| 402 | plan_required | Managing streams and webhooks with a live key requires the Growth plan or above (test keys are exempt). | Upgrade your plan or use a test key. |
| 403 | insufficient_scope | Key lacks the scope for this endpoint. | Create a key with the needed scope. |
| 403 | vertical_mismatch | vertical in the request ≠ your brand's vertical, or platform is not permitted for your brand's vertical. | Drop the vertical field (defaults to your brand), or pick a platform your vertical may stream to — iGaming is limited to kick, youtube and twitch. |
| 404 | not_found | Resource doesn't exist or belongs to another brand. Ending a stream that isn't live also returns this. | Check the id, or wait for the stream to be live before ending it. |
| 429 | rate_limited | Over the per-minute request limit. | Back off before retrying. |
| 429 | concurrency_limit | Brand already has 3 active (preparing+live) streams. | End one before starting another. |
| 500 | db_error | Something failed on our side. | Retry with backoff; contact support if persistent. |
| 502 | launch_failed | Stream dispatch to the agent worker failed. | Retry — this is usually transient. If persistent, contact support. |
Rate limits
| Limit | Applies to |
|---|---|
| 100 requests/min | All v1 endpoints except public GET /creators |
The limit is per brand, per minute, fixed window. When you hit it you'll get a 429 rate_limited. GET /api/v1/creators is public and not rate-limited. 429 concurrency_limit is separate — retrying won't clear it, end a stream first.
Limits are applied in-memory and reset on deploy. If you're polling stream status, switch to webhooks — it's what they're for.
Idempotency & retries
GET/DELETEare safe to retry freely.- For
POST /streams: if your request times out, checkGET /streamsbefore retrying — the stream may have been created. - Webhook deliveries are at-least-once; dedupe on the event
id.
Abuse prevention
Keys used for probing, scraping, or exceeding rate limits without prior arrangement may be revoked. If you need higher limits, email us — we're happy to accommodate legitimate traffic.
Was this page helpful?