Errors and limits
Error format
Every non-2xx response is shaped as:
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable description.",
"field": "optional — name of the offending input field for 4xx",
"howToFix": "what to do next — present whenever the code is in the catalog"
}
}Always present alongside the body: X-DCAST-Request-Id response header. Quote it in any support ticket so we can grep the exact request lifecycle.
Every error answer that carries a code also carries error.howToFix: one or two sentences on what to do next. The complete list, with when each code comes and its howToFix, is served at https://api.dcast.pro/docs/errors.json and as x-dcast-error-catalog in openapi.json; the errors of one operation are its x-dcast-errors, and an AI connector shows them in dcast_describe_operation.
Error codes
| Code | HTTP | Description |
|---|---|---|
UNAUTHORIZED | 401 | No API key sent |
INVALID_KEY_FORMAT | 401 | The key does not start with pk_ |
INVALID_KEY / KEY_DISABLED / KEY_EXPIRED | 401 | Unknown, revoked or expired key |
INVALID_USER_TOKEN | 401 | X-User-Token present but invalid, expired, or for a different user than the key owner |
INSUFFICIENT_SCOPE | 403 | The key's scope does not allow this HTTP method (e.g. a READ_ONLY key sending a write) |
PERMISSION_DENIED | 403 | The key lacks a required permission (e.g. videos:write) |
FINANCIAL_SCOPE_REQUIRED | 403 | Money endpoint called without FULL_ACCESS or a finance:* permission |
STRIPE_VERIFICATION_REQUIRED | 403 | Paid access (a paid video or stream, or a tier) was requested before the account finished Stripe onboarding. Finish it in the DCAST dashboard, then repeat the call. |
DHUB_REQUIRES_ADDON | 403 | A DHUB bridge action that spends worker capacity was called on an account without the DHUB add-on or a plan that includes it. |
NO_PAYOUT_GATEWAY | 403 | Paid access (isPaid with a price) was requested on a video or stream, but the account has no payout gateway connected (Stripe, PayPal, Monobank or crypto). Connect one in the DCAST dashboard, then repeat the call. |
STREAM_NOT_ACTIVE | 400 | POST /streams/:id/start was called before any signal reached the stream key. Publish from your encoder, wait for hasSignal=true, then repeat the call. |
OWNER_SCOPE_REQUIRED | 403 | Minting a key, or revoking another key, without a FULL_ACCESS key or X-User-Token |
VERIFICATION_REQUIRED | 403 | The email address is not confirmed yet and the one free first item of this kind (stream, restream, room or video) is already used. Confirm the email to add more. |
IP_NOT_ALLOWED / DOMAIN_NOT_ALLOWED | 403 | The key is restricted to other IPs / domains |
ADMIN_ONLY | 403 | Admin-gated endpoint called with a creator key |
integration_domain_required / origin_not_allowed | 403 | Checkout origin lock. The body is { "success": false, "error": "<code>" } (a string, not an object). See Domain verification. |
METHOD_NOT_ALLOWED | 405 | The path exists but not with this method; see the Allow header |
NOT_FOUND | 404 | Resource not found (also returned for foreign resources — we never leak existence) |
BAD_REQUEST | 400 | Invalid parameters. error.field names the offending input. |
INVALID_STATUS | 400 | The status filter of GET /videos is not one of the allowed values. |
INVALID_VISIBILITY | 400 | The visibility value is not recognised (video and stream writes). |
UNSUPPORTED_FIELD | 400 | PATCH /videos/:id or PATCH /streams/:id received a field they do not support, such as currency. error.field names it. |
PRICE_REQUIRED | 400 | Paid access was switched on without a price above zero (PATCH /videos/:id, PATCH /streams/:id). error.field is price. |
VIMEO_TOKEN_INVALID / VIMEO_TOKEN_SCOPE / VIMEO_NO_ACCESS / VIMEO_NOT_FOUND / VIMEO_DOWNLOAD_UNAVAILABLE / VIMEO_REFERENCE_INVALID | 422 | Vimeo refused the import. The token was not accepted, lacks a scope (public, private, video_files), has no access to the video, the video does not exist in that Vimeo account, downloads are switched off on Vimeo, or an item is not a Vimeo video id or link. Answered by POST /videos/import/vimeo; error.code names which; fix it on the Vimeo side or in the request and send again. |
CSV_NO_EMAIL_COLUMN | 400 | The buyer CSV has several columns and no header names the address column. Answered by POST /videos/{id}/buyers/preview and /confirm (and the /streams/ ones). The address column is the one whose header contains “email” or “e-mail” (an exact “email” wins), as in a Vimeo “Export email addresses” file; add such a header or send one column of addresses, then preview again. |
VIMEO_RATE_LIMITED / VIMEO_UNAVAILABLE | 502 | Vimeo is limiting requests or could not be asked. Answered by POST /videos/import/vimeo; try again in a few minutes. |
PRICE_BELOW_PLAN_MIN | 400 | A paid price was saved below the minimum of the account's plan: $5 on Free, $5 on Star, $3 on Pro, $3 on VIP, in USD (another currency is converted at the bank rate). Answered when a video, stream, course, membership tier, booking product or room is saved with a new or changed price; a price saved earlier keeps selling. error.details carries plan, priceUsd, minUsd and maxUsd. |
PRICE_ABOVE_PLAN_MAX | 400 | A paid price was saved above the maximum of the account's plan: $20 on Free, $100 on Star, $250 on Pro, — on VIP, in USD (a dash means no maximum). Judged like PRICE_BELOW_PLAN_MIN; a higher plan allows a higher price from the moment it is bought. |
SELLER_TURNOVER_LIMIT_REACHED | 409 | The seller's sales this month have reached the plan's turnover limit: $250 on Free, $2,500 on Star, $7,500 on Pro, — on VIP, in USD (a dash means no limit). Every sale counts, donations included, on every payment method; the month starts on the day the account registered or last changed plan. Answered to the buyer at checkout, with no figure. The seller sees the turnover used in Analytics and lifts the limit at once by moving to a higher plan. |
FORBIDDEN_FIELD | 403 | PATCH /me received an identity, role or plan field (such as email, role or plan), which cannot be changed through the API. |
WEBHOOK_INACTIVE | 400 | POST /me/webhooks/:id/test or a delivery replay on a webhook that is switched off. Switch it on first: PATCH /me/webhooks/:id with isActive: true. |
INVALID_IDEMPOTENCY_KEY | 400 | Idempotency-Key format failed [A-Za-z0-9_-]{8,255} |
IDEMPOTENCY_IN_FLIGHT | 409 | A prior request with this Idempotency-Key is still being processed |
PLAN_STREAM_LIMIT_REACHED | 409 | Starting a live stream would exceed the plan's number of concurrent live streams. limit is the plan's allowance and current is how many streams are on air now. |
PLAN_RESTREAM_LEG_LIMIT_REACHED | 409 | Switching on one more outgoing restream leg would exceed the plan's number of legs on air at once, counted over the whole account rather than per restream: 2 on Free, 4 on Star, 6 on Pro, 10 on VIP. A leg counts while it is switched on (enabled: true) on a restream that is running. Answered by POST /restreams/:id/start, and by PATCH /restreams/:id/destinations/:destId and PUT /restreams/:id when they switch a leg on while the restream is running. limit is the plan's allowance, current the legs your other running restreams hold, wanted the legs this restream would hold, total their sum and plan the account plan. |
IDEMPOTENCY_KEY_REUSE | 422 | Same Idempotency-Key was used with a different body |
RATE_LIMITED | 429 | Per-key rate limit exceeded (also the per-endpoint caps on chat posts, subscriber adds and login). See Retry-After + X-RateLimit-Reset for when to retry. |
RATE_LIMIT | 429 | Only on POST /videos/:id/views: too many view events from one IP for one video |
SSE_PER_KEY_CAP | 429 | Too many concurrent SSE tails (chat / status / viewers) on one key |
QUOTA_EXCEEDED | 403 | Storage or plan limit exceeded |
INTERNAL_ERROR | 500 | Server error. The X-DCAST-Request-Id identifies it in our logs. |
Some endpoints use a specific code for a bad filter or field value (for example INVALID_STATUS), others answer BAD_REQUEST. Read error.field to find the offending input.
The code on a key-level rate limit is RATE_LIMITED; RATE_LIMIT_EXCEEDED is never returned. One exception to the envelope: the per-IP limiters on POST /auth/login, /channel/* and /videos/:id/related answer 429 with { "success": false, "error": "Too many requests", "retryAfter": <seconds> }.
Player errors
The addresses a viewer's player calls (/api/streams/:id/access-token, /api/videos/:id/access-token and the master addresses) answer in their own shape: { "success": false, "error": "text", "code": "CODE", "howToFix": "what to do" }. Branch on code, never on the text. The text and howToFix may be reworded; the code and the status are the contract.
| Code | HTTP | Description |
|---|---|---|
STREAM_NOT_FOUND / VIDEO_NOT_FOUND / CONTENT_NOT_FOUND | 404 | No stream or video with this id, or it was deleted. Do not retry. |
STREAM_DELETED / ORPHAN_ARTIFACT / NO_DELIVERY_WORKER | 410 | The card was deleted or its media is gone from storage. Stop asking. |
STREAM_NOT_LIVE | 409 | The viewer may watch, but the broadcast has not started or was interrupted. Show the waiting state and ask again after the Retry-After header (30 seconds). The answer carries state, title and scheduledStartAt. |
STREAM_MANIFEST_NOT_READY / CONTENT_EMPTY | 404 | STREAM_MANIFEST_NOT_READY: the broadcast is running but its playlist is not published yet; ask again after Retry-After (2 seconds). CONTENT_EMPTY: the card has nothing to play; do not retry. |
STREAM_PRIVATE / CONTENT_PRIVATE / CONTENT_REMOVED / CONTENT_ACCESS_MISCONFIGURED / GRANT_REQUIRED / REPLAY_EXPIRED | 403 | The card is private, was removed for a policy violation, has an invalid access setting, needs a grant from the author, or its replay window has ended. Do not retry. |
REGISTRATION_REQUIRED / ACCESS_KEY_REQUIRED / INVALID_CODE / SUBSCRIPTION_REQUIRED / PURCHASE_REQUIRED / TIER_REQUIRED / TICKET_REQUIRED | 403 | The viewer has not yet done what the card asks: registered, entered the access key or code, subscribed, bought it, joined the tier or got a ticket. Offer that step, then ask again. alternatives and the other fields of the answer name the options. |
SEAT_TAKEN | 403 | The access key plays on another device and this automatic renewal kept no seat. Do not retry by itself: tell the viewer, and offer “watch here”, which asks again without seat=keep and takes the seat. |
SHARED_KEY_SEATS_FULL | 403 | The card's single access key, shared by everyone, has a set number of seats, and every seat is in use. Tell the viewer, then ask again later: a seat frees when a viewer stops watching. |
ACCESS_KEY_INVALID | 403 | The key the viewer typed does not match any key of this card. Do not resend the same key: ask the viewer to check it for typos and enter it again. alternatives, when present, names the other ways in. |
ACCESS_KEY_REVOKED | 403 | The key exists, but the author turned it off. Tell the viewer; only the author can turn it back on or give a new key. Do not retry. |
ACCESS_KEY_EXPIRED | 403 | The key exists, but its validity date has passed. The answer carries expiredAt when the date is known. Tell the viewer; only the author can extend the key or give a new one. Do not retry. |
ACCESS_KEY_USED_UP | 403 | The key exists, but it has already been used the maximum number of times. Tell the viewer; only the author can raise the limit or give a new key. Do not retry. |
ACCESS_KEY_OTHER_CARD | 403 | The key exists, but it was issued for a different broadcast or video. Tell the viewer to use the key of this card. Do not retry. |
LOGIN_REQUIRED | 401 | The card needs a signed-in viewer. Ask the viewer to sign in, then ask again. |
MASTER_PASS_REQUIRED / INVALID_TOKEN | 401 | The master address was asked without a playback pass (MASTER_PASS_REQUIRED), or the pass sent with it is invalid or expired (INVALID_TOKEN). A master address plays only with a pass. Ask the access-token address of the card (accessTokenUrl in the answer) and play the masterUrl it returns, or put the DCAST embed player on the page. |
EMBED_SITE_NOT_ALLOWED / ORIGIN_NOT_ALLOWED / EXTERNAL_PLAYER_NOT_IN_PLAN / CORS_REFUSED / MASTER_TOKEN_REQUIRED / MASTER_TOKEN_INVALID | 403 | The page that shows the player is not allowed: the author shows the content only on their own sites, the owner's plan has no external player, or the pass is missing or no longer valid. The answer does not name the author's sites. Watch on the author's own site, or ask the access-token address again for a fresh pass. |
ACCESS_KEY_UNAVAILABLE / CONTENT_UNAVAILABLE / DELIVERY_WORKER_UNAVAILABLE / DELIVERY_LOOKUP_FAILED / NO_LIVE_HOLDER / EXTERNAL_PLAYER_CHECK_UNAVAILABLE | 503 | Temporary. Ask again after the Retry-After header (5 seconds, 30 for NO_LIVE_HOLDER) or in a few seconds. |
RATE_LIMITED | 429 | More requests from one address than the platform allows in 15 minutes (the same code as the key limit above). Wait for Retry-After. |
BAD_REPORT | 400 | The problem report is not in the expected shape: streamId, kind (live or vod) and text are required, or no broadcast or video has this id. The message names the field. Fix it and send again. |
REPORT_TOO_LARGE | 413 | The problem report is larger than allowed: body 64 KB, text 48 KB, client object 16 KB. Shorten it (keep the newest lines) and send again. |
REPORT_RATE_LIMITED | 429 | Too many problem reports from this viewer, player session or broadcast in a short time. Wait for retryAfterSec seconds before sending another; the earlier reports were received. |
INTERNAL_ERROR | 500 | Server error. Ask once more; if it repeats, contact support and quote the time. |
Rate limit headers
Every response to a request whose key passed authentication (including later 4xx and 5xx) carries the headers below; a 401/403 from the key check itself carries none:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current 60-second window for your pk_* key. |
X-RateLimit-Remaining | Requests left in this window. Reaches 0 when the next request would 429. Value -1 = backend rate-limit storage temporarily unavailable; the request was allowed through, throttle conservatively. |
X-RateLimit-Reset | Unix epoch (seconds) when the current window closes and the counter resets. |
Retry-After | Only on 429. Seconds to wait before retrying. |
X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining, X-RateLimit-Daily-Reset | Only on a key with a daily quota. Over the quota the answer is 429 DAILY_QUOTA_EXCEEDED; the quota resets at 00:00 UTC. |
Dcast-Key-Mode | live or test — the mode of the key that made the call (see Test mode). |
Limits are per-pk_* key. Each key has its own bucket and does not affect other keys. A key created in the dashboard (Settings → API Keys) defaults to 10000 req/min; a key minted with POST /me/api-keys gets 1000 req/min. Either may also carry an optional daily quota.
Soft-throttle on your side using X-RateLimit-Remaining — hitting 429 is recoverable, but hammering 429s wastes round-trips. Industry pattern: when Remaining < Limit * 0.1 back off for the rest of the window.
Per-endpoint rate limits (current overrides)
| Scope | Limit |
|---|---|
| General partner-API | The key's own per-minute limit (see above) |
POST /streams/:id/chat | 60 per minute per key per stream; 1000 per day per stream |
POST /subscribers, POST /users/:username/subscribe | 100 and 60 per hour per key respectively (429 RATE_LIMITED) |
/channel/*, /videos/:id/related (public) | 60 req/min per IP |
POST /videos/:id/views (public) | 30 req/min per IP |
POST /auth/login | 10 per 15 min per IP; 100 per hour per key |
| SSE tails per key (chat / status / viewers) | 25 concurrent connections per key |
File limits
- Video file: up to 100 GB
- Duration: up to 12 hours
- Uploaded-video resolution: up to 8K (4320p) (7680×4320) on VIP; the top rung is set by the plan — 720p Free, 1080p Star, 4K (2160p) Pro
- Live resolution: up to 4K (2160p) on VIP — 720p Free, 1080p Star, 2K (1440p) Pro. The live ladder is separate from the video ladder and is one rung lower on Pro.
- Frame rate: up to 120 fps for uploaded video, up to 60 fps live — identical on every plan, Free included. These are ceilings, not targets: a 25 fps source is delivered at 25 fps.

