Errors
Every failure is an RFC 9457 problem document with a stable code.
Errors are RFC 9457 problem details (application/problem+json). Branch on code, which never changes; detail is for people and its wording can.
{
"type": "https://api-docs.vidyst.com/docs/errors#invalid_api_key",
"title": "Unauthorized",
"status": 401,
"detail": "The API key is invalid. Check that you copied the whole key.",
"instance": "/public/v1/auth/verify",
"code": "invalid_api_key",
"requestId": "0192f5e2-7c1a-7c4e-9a51-3d1f0b6c2e11"
}| Status | Codes | What to do |
|---|---|---|
400 | invalid_request, invalid_cursor | Fix the request; errors lists every invalid field. A stale cursor: start the list again. |
401 | missing_api_key, invalid_api_key, expired_api_key, revoked_api_key | Send a valid key. Don't retry with the same key. |
402 | licence_inactive | The licence named isn't active. Renew it, or use another. |
403 | api_access_disabled, ip_not_allowed, insufficient_scope | The key is valid but may not do this. Change the key's settings in the studio. |
403 | webinars_not_enabled, licence_assigned, licence_limit, feature_locked | The account or the licence doesn't allow this. |
404 | not_found, licence_not_found | The resource doesn't exist, or isn't yours. |
409 | idempotency_conflict, conflict | An Idempotency-Key was reused with another body, its first request is still running, or the change isn't possible right now. |
410 | webinar_ended | The webinar has ended and can't change. |
412 | precondition_failed | It changed since you read it (If-Match). Read it again, then retry. |
413, 415 | payload_too_large, unsupported_media_type | Fix the request body or its Content-Type. |
429 | rate_limited | Wait Retry-After seconds. |
5xx | server_error, upstream_error, overloaded, webinars_unavailable | Retry with exponential backoff. |
The fields
| Field | Is |
|---|---|
code | The stable identifier to branch on. |
status | The HTTP status, repeated in the body. |
title | A short, generic name for the status. |
detail | A sentence for people. Show it, don't parse it. |
instance | The path that failed. |
requestId | This request's id, also in the X-Request-Id header. See Request ids. |
type | A URL identifying the error class: this page, with the code as its anchor. |
errors | On invalid_request only: one entry per invalid field. |
required | On insufficient_scope only: the scope the key needs. |
Retrying
Retry on 429 and on 5xx, nothing else. Any other 4xx means the request itself has to change, so retrying it unchanged fails the same way.
For 5xx, back off exponentially (for example 1s, 2s, 4s, 8s) with jitter, and give up after a handful of attempts. When a 503 carries Retry-After, use it. Keep the requestId of the failures: it's what support needs to find them.
The codes
invalid_request
400. The request doesn't match what the endpoint accepts: a missing or malformed field, or a body that isn't valid JSON. errors lists every field that failed, so you can fix them in one pass:
{
"type": "https://api-docs.vidyst.com/docs/errors#invalid_request",
"title": "Bad Request",
"status": 400,
"detail": "The request is invalid.",
"instance": "/public/v1/auth/verify",
"code": "invalid_request",
"errors": [{ "path": "title", "code": "too_big", "message": "Title must be 1–200 characters." }],
"requestId": "0192f5e2-7c1a-7c4e-9a51-3d1f0b6c2e11"
}invalid_cursor
400. The cursor isn't one the API gave you, or you sent it with a different sort or different filters than the page it came from. A cursor only continues the list it was made for. Start again without it. See Pagination.
missing_api_key
401. No Authorization header. Send your key as Authorization: Bearer vk_live_…. See Authentication.
invalid_api_key
401. The key isn't one we know, or its secret doesn't match. Check that you copied the whole key, and that you're using a live key against production rather than a truncated or edited copy.
expired_api_key
401. The key passed the date in its expiresAt. Every key expires: create a replacement in the studio, and watch expiresAt from GET /auth/verify so you're not surprised.
revoked_api_key
401. The key was revoked, by you in the studio or by Vidyst if it was found leaked. Create a new key; the old secret will never work again.
api_access_disabled
403. The key is valid, but API access isn't enabled for the account that owns it. Contact support if you expect it to be.
ip_not_allowed
403. The key has an IP allowlist and this request didn't come from it. Add the address of the server making the call, or clear the allowlist, in the studio.
insufficient_scope
403. The key is valid but lacks the scope the endpoint needs. The scope is in required, so you can report exactly what's missing:
{
"type": "https://api-docs.vidyst.com/docs/errors#insufficient_scope",
"title": "Forbidden",
"status": 403,
"detail": "This API key doesn't have the `webinars:read` permission. Edit the key in the Vidyst studio to add it.",
"instance": "/public/v1/auth/verify",
"code": "insufficient_scope",
"required": "webinars:read",
"requestId": "0192f5e2-7c1a-7c4e-9a51-3d1f0b6c2e11"
}Grant it by editing the key in the studio. See Scopes.
webinars_not_enabled
403. The key is valid, but webinars aren't enabled for its account yet. Contact support if you expect them to be.
licence_inactive
402. The licence in licenceKey isn't active: unpaid, cancelled or ended. Renew it in the studio, or create the webinar on another licence.
licence_assigned
403. The licence belongs to your account but is assigned to someone else, so only they can run webinars on it. Use a licence you hold.
licence_limit
403. The licence's limit is reached (for instance, how many webinars it runs at once). The response says which limit, in limit. Add capacity to the licence or use another one.
feature_locked
403. The licence doesn't include a feature the request uses. The response names it.
not_found
404. The resource doesn't exist, or it isn't on the account the key belongs to: the two are deliberately indistinguishable, so one account can't probe another's ids. Check the id and the key.
licence_not_found
404. No licence with that licenceKey is one you can use: it doesn't exist, or it isn't yours. Copy the key from the studio's Licences page.
idempotency_conflict
409. The Idempotency-Key was already used, within the last 24 hours, for a request with a different body. Use a new key for a new request. See Idempotency.
conflict
409. The first request with this Idempotency-Key is still being processed. Wait a moment and retry with the same key: you'll get its result.
webinar_ended
410. The webinar has ended (its last session is over, or the host ended it for good), so it can't be edited any more.
precondition_failed
412. You sent If-Match with the webinar's ETag, and the webinar has changed since: someone else edited it in between. Nothing was changed. editVersion in the response is its current version. Read the webinar again (GET), re-apply your change to what's there now, and send it with the new ETag. See Editing safely.
payload_too_large
413. The request body is over 1 MiB. Send less in one call, for instance by paging through a long list of changes rather than sending them all at once.
unsupported_media_type
415. The body wasn't JSON. Send Content-Type: application/json and a JSON body.
rate_limited
429. Too many requests for the key or for your IP address. Wait the number of seconds in Retry-After, then retry; the RateLimit-* headers say where you stand. See Rate limits.
server_error
500. Something went wrong on our side, and the request may or may not have taken effect. Retry with exponential backoff, and send support the requestId if it keeps happening.
upstream_error
502. A Vidyst service behind the API failed or answered something unexpected. Retry with exponential backoff; with an Idempotency-Key, a retry is safe.
overloaded
503. Vidyst is temporarily too busy to take the request. Nothing happened, so it's safe to retry: wait for Retry-After when it's there, else back off and try again.
webinars_unavailable
503. Webinars are temporarily unavailable. Retry with backoff.