Skip to content
Documentation

RTC errors

Every RTC error carries a stable, machine-readable code. Switch on the code, never on the message text: messages may be reworded, codes are never renamed or reused for another meaning.

Default. Without a version header, errors keep their original shape, so existing integrations are unaffected:

{ "error": "Your plan allows 2 webhook endpoints", "code": "WEBHOOK_ENDPOINT_LIMIT" }

code is present on errors that have a specific code. Older errors may only carry error; the X-Error-Code header always names the code.

Structured envelope. Send RTC-Version: 2026-11-01 with a request to receive the structured envelope:

Terminal window
curl https://api.rtc.champrep.com/v1/webhooks/endpoints \
--header "Authorization: Bearer $RTC_API_KEY" \
--header "RTC-Version: 2026-11-01" \
--header "Content-Type: application/json" \
--data '{ "url": "https://hooks.example.com/rtc" }'
{
"error": {
"code": "WEBHOOK_ENDPOINT_LIMIT",
"message": "Your plan allows 2 webhook endpoints",
"details": { "limit": 2, "used": 2 },
"requestId": "6f1c2b8e-1d2a-4c55-9a8e-0f4b9b1d7c21",
"retryable": false,
"docUrl": "https://docs.champrep.com/services/rtc/errors/#webhook-endpoint-limit"
}
}
FieldMeaning
codeStable code from the catalog
messageHuman-readable explanation; do not parse it
detailsOptional structured context, for example limit and used, or issues (the invalid fields) for INVALID_REQUEST
requestIdThe id of this request, also sent as X-Request-Id
retryabletrue when retrying the same request later can succeed
docUrlLink to this code’s entry below

The response echoes the version it applied in the RTC-Version header. A date before 2026-11-01 keeps the default shape. See versioning.

HeaderWhenMeaning
X-Request-IdEvery responseUnique id of the request. Include it when you contact support.
X-Error-CodeEvery errorThe stable code, in both response shapes
Retry-After429, and some 503Seconds to wait before retrying
X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-ResetAuthenticated responsesSee rate limits
  • retryable: false (4xx other than 429): fix the request, credential, plan or state first. Repeating it unchanged gives the same answer.
  • retryable: true: retry with exponential backoff and jitter, honouring Retry-After. Retry writes only when the operation is idempotent or after reconciling its result.
  • 401: the credential is missing, expired or revoked. 403: the credential is valid but lacks a scope, project access or plan entitlement.
  • 404 also covers resources that belong to someone else. Never probe other customers’ identifiers.

GET /v1/error-codes (no authentication) returns the current catalog as { "codes": [{ "code", "status", "retryable", "description" }] }. New codes may be added at any time; treat an unknown code like the generic code of its HTTP status.

Generic codes (one per HTTP status, used when no specific code applies)

Section titled “Generic codes (one per HTTP status, used when no specific code applies)”
CodeHTTPRetryableMeaning
INVALID_REQUEST400noThe request is malformed or a field is invalid (details.issues lists the fields).
UNAUTHENTICATED401noMissing, invalid or expired credentials.
PAYMENT_REQUIRED402noA payment is due before this can be used.
FORBIDDEN403noThe credential is valid but not allowed to do this.
NOT_FOUND404noThe resource does not exist or is not visible to this credential.
CONFLICT409noThe request conflicts with the current state.
PAYLOAD_TOO_LARGE413noThe request body is too large.
UNSUPPORTED_MEDIA_TYPE415noThe content type is not accepted.
RANGE_NOT_SATISFIABLE416noThe requested byte range is invalid or unavailable.
UNPROCESSABLE422noThe content was understood but cannot be processed.
RATE_LIMITED429yesToo many requests; wait for Retry-After seconds.
INTERNAL500yesUnexpected server error; retry later.
SERVICE_UNAVAILABLE503yesTemporarily unavailable; retry with backoff.

These answers also carry offers (what fixes it: a trial, a subscription, an upgrade, a pack or adding a card, each a CHAMPREP Billing link) and, where one allowance or feature is meant, feature.

CodeHTTPRetryableMeaning
RTC_SUBSCRIPTION_REQUIRED402noThe account has no RTC subscription, trial or included allowance (see offers).
RTC_PAYMENT_REQUIRED402noAn unpaid invoice blocks RTC; pay it in CHAMPREP Billing.
RTC_ACCESS_DENIED403noAn organization, team or platform policy denies RTC (reasonCode says which).
RTC_ALLOWANCE_EXHAUSTED402noAn RTC allowance of the subscription is used up (feature says which; see offers).
RTC_FEATURE_NOT_IN_PLAN403noThe subscription does not include this feature (see offers).
RTC_PLAN_LIMIT403noA limit of the subscription is reached (room size, rooms open at the same time).
PAYMENT_METHOD_REQUIRED402noThe trial needs a saved card on the paying workspace (see offers).
TRIAL_ALREADY_USED409noThe free trial was already used by this account.
TRIAL_NOT_ALLOWED403noThis account cannot start the free trial.
TRIAL_UNAVAILABLE409noThe free trial is not available.
ALREADY_SUBSCRIBED409noThe account already has an RTC subscription.
PRIMARY_TOKEN_REQUIRED401noStarting a trial needs the account owner’s console session.
PRIMARY_TOKEN_INVALID401noThe console session is not valid for starting a trial; sign in again.
PRIMARY_TOKEN_MISMATCH403noOnly the account owner can start this trial.
CodeHTTPRetryableMeaning
INVALID_CURSOR400noThe cursor is malformed or belongs to another list.
IDEMPOTENCY_KEY_INVALID400noThe Idempotency-Key header is malformed.
IDEMPOTENCY_KEY_REUSED409noThe Idempotency-Key was used with a different request.
IDEMPOTENCY_IN_PROGRESS409yesThe first request with this Idempotency-Key is still running.
CodeHTTPRetryableMeaning
ROOM_EXTERNAL_REF_CONFLICT409noAn open room of the project already uses this externalRef.
ROOM_FULL409noThe room has reached its participant limit.
ROOM_LOCKED409noThe room is locked; only hosts can join.
ROOM_ALLOWANCE_UNAVAILABLE503yesThe room participant allowance could not be read.
PARTICIPANT_BANNED409noThis identity is banned from the room.
PARTICIPANT_REMOVED403noThis participant was removed from the room.
MEDIA_CAPACITY503yesNo media node has room for this now; retry later.
MEDIA_NODE_UNAVAILABLE503yesThe room’s media node is unavailable; retry.
MEDIA_UNAVAILABLE503yesThe media service is unavailable; retry.
HOST_MUTED403noA host muted this source.
DATA_NOT_PERMITTED403noThe participant may not send app messages.
MESSAGE_TOO_LARGE400noThe app message is too large.
MESSAGE_RATE_LIMITED429yesToo many app messages from this participant.
ROOM_MESSAGE_RATE_LIMITED429yesToo many app messages in this room.
RESERVED_TOPIC400noThe app message topic is reserved.
INVALID_RECIPIENTS400noThe app message recipients are invalid.
RESUME_REFUSED403noThe session cannot be resumed.
RESUME_UNAVAILABLE503yesResume is temporarily unavailable.
FIRST_PARTY409noReserved for CHAMPREP’s own products.
FIRST_PARTY_NOT_READY503yesThe first-party tenant is not provisioned yet.
CodeHTTPRetryableMeaning
JOIN_GRANT_INVALID401noThe join token is malformed, expired, wrongly signed or its signing key is revoked.
JOIN_GRANT_USED409noThis join token was already exchanged (they are single use).
SIGNING_KEY_LIMIT409noThe project already has the maximum number of active signing keys.
SIGNING_KEY_INVALID400noThe public key is not a valid P-256 JWK.
CodeHTTPRetryableMeaning
COMPOSITE_UNAVAILABLE400noComposite recording is not available.
DELETE_NOT_AVAILABLE403noRecordings cannot be deleted by customers (no longer sent: DELETE /v1/recordings/:id sends the recording to Trash, auto-deleted after 30 days).
RECORDING_ACTIVE409noThe recording is still running.
RECORDING_SETTLING409yesThe recording is still being stored.
RECORDING_NOT_READY409noThe recording is not finished yet (deliveries need a ready recording).
RECORDING_NOT_IN_TRASH409noOnly a recording in Trash can be deleted permanently; delete it first.
RECORDING_PURGED409noThe recording was deleted permanently (from Trash, or by an administrator) and cannot be restored.
CONFIRM_PURGE_REQUIRED400noShortening the Trash window needs confirmPurge: true.
TRANSCRIPTION_UNAVAILABLE400noTranscripts are not available for this account.
TRANSCRIPT_EXISTS409noA transcript of this recording already exists or is running.
NO_AUDIO409noThe recording has no audio to transcribe.
TRANSCRIPT_NOT_READY409yesThe transcript is not done yet; only a done transcript exports as VTT, SRT or TXT.
TRANSCRIPT_RUNNING409noThe transcript is already being made and cannot be cancelled.
TRANSCRIPT_NOT_CANCELLABLE409noOnly a transcript that has not started can be cancelled.
WINDOW_TOO_LONG400noThe requested time window is too long.
SUMMARY_TIMEOUT503yesThe summary took too long; retry.
CAPTIONS_BUSY503yesLive captions are at capacity; retry later.
CAPTIONS_LANGUAGE_LIMIT409noToo many caption languages in this room.
CAPTIONS_NOT_PERMITTED403noThe participant may not use captions.
INVALID_LANGUAGE400noThe language code is not supported.
CodeHTTPRetryableMeaning
DESTINATION_LIMIT409noThe organization has the maximum number of storage destinations.
DESTINATION_ADMIN_DISABLED403noCHAMPREP support disabled this storage destination; it cannot be re-enabled by the customer.
ENDPOINT_NOT_ALLOWED400noThe S3-compatible endpoint is not allowed (HTTPS on 443 to a public address only).
REDELIVERY_LIMIT429yesThe recording was sent again recently, or the organization sent too many again this hour; retry later.
NO_ACTIVE_DESTINATION409noNo active storage destination applies to this recording.
EGRESS_UNAVAILABLE503yesBilling could not be reached to cover this download; try again shortly.
DELIVERY_NOT_CONFIGURED503noAWS role destinations are not available yet; use S3-compatible keys (code and message are sent).
CREDENTIALS_UNAVAILABLE503noStoring destination keys is not available yet; use an AWS role.
CodeHTTPRetryableMeaning
WEBHOOK_NOT_CONFIGURED409noNo webhook endpoint is configured.
WEBHOOK_URL_INVALID400noThe webhook URL is not a public HTTPS endpoint on port 443 outside CHAMPREP domains.
WEBHOOK_ENDPOINT_LIMIT409noThe plan’s number of webhook endpoints is reached (details.limit, details.used).
WEBHOOK_ENDPOINT_NOT_FOUND404noThe webhook endpoint does not exist.
WEBHOOK_ENDPOINT_DISABLED409noThe webhook endpoint is disabled; enable it first.
WEBHOOK_ENDPOINT_ADMIN_DISABLED403noCHAMPREP support turned the webhook endpoint off; contact support.
WEBHOOK_URL_ADMIN_DISABLED403noCHAMPREP support turned this webhook URL off; it cannot be added again. Contact support.
WEBHOOK_EVENT_UNKNOWN400noAn event filter matches no known event type (details.patterns).
REPLAY_LIMIT409noThis delivery was replayed too often.
REPLAY_QUOTA429yesToo many replays; wait for Retry-After seconds.
DELIVERY_IN_PROGRESS409yesThe delivery is being sent right now.
CodeHTTPRetryableMeaning
WHITEBOARD_UNAVAILABLE503yesThe whiteboard service is unavailable.
WHITEBOARD_DISABLED403noWhiteboards are turned off for this account.
WHITEBOARD_ARCHIVED409noThe whiteboard is archived.
WHITEBOARD_LIMIT409noThe room has the maximum number of whiteboards.
WHITEBOARD_QUOTA402noThe whiteboard allowance is used up.
WHITEBOARD_FILE_INVALID422noThe whiteboard file could not be read.
WHITEBOARD_FILE_LIMIT409noThe whiteboard has the maximum number of files.
WHITEBOARD_FILE_PENDING409yesThe whiteboard file upload is not finished.
WHITEBOARD_FILE_SIZE400noThe declared file size is invalid.
WHITEBOARD_FILE_TOO_LARGE413noThe whiteboard file is too large.
WHITEBOARD_FILE_TYPE415noThe whiteboard file type is not allowed.
SNAPSHOT_TOO_LARGE413noThe whiteboard snapshot is too large to return.
CodeHTTPRetryableMeaning
RC_BLOCKED403noRemote control is blocked.
RC_CLIPBOARD_OFF403noClipboard sharing is off.
RC_CLIPBOARD_TOO_LARGE413noThe clipboard content is too large.
RC_CONFLICT409noAnother remote control request conflicts.
RC_INVALID_REQUEST400noThe remote control request is invalid.
RC_NOT_PERMITTED403noRemote control is not permitted.
RC_NO_BUDGET402noNo remote control allowance is left.
RC_PENDING409noA remote control request is already pending.
RC_RATE_LIMITED429yesToo many remote control requests.
RC_REAUTH_REQUIRED401noRe-authenticate to continue remote control.
RC_SHARER_BUSY409noThe sharer is already controlled.
RC_UNAVAILABLE404noRemote control is unavailable.
RC_WIDEN_REFUSED403noThe remote control grant cannot be widened.
CodeHTTPRetryableMeaning
INVALID_TELEMETRY400noThe telemetry sample is invalid.
TELEMETRY_RATE_LIMITED429yesToo many telemetry samples.