Skip to content

YouTube API errors: codes, causes, and fixes

YouTube API errors are easiest to diagnose by category: authentication, quota, metadata, policy, upload, or lookup. This guide covers 15 documented YouTube Data API v3 errors, including quotaExceeded, with the HTTP status, plain-English cause, and the fix to try first. Start with the error code in the quick-reference table, then use the category section for the checks that distinguish a retryable request problem from a channel, quota, or account problem that needs a different remedy.

How to use this guide by category

YouTube Data API v3 failures cluster into six categories. Authentication errors mean the request was blocked before the operation could run, usually because of scopes, token state, or a Google account without a linked channel. Quota errors mean the project or channel budget is exhausted. Metadata errors mean a field such as snippet.title, snippet.categoryId, or the description failed validation. Policy errors mean the requested privacy, license, or account state is not allowed. Upload errors mean the request body or required parameters were incomplete. Lookup errors mean the video or channel identifier does not resolve. Use the category to decide the first check: reconnect or re-scope for authentication, budget or cap checks for quota, field validation for metadata, a safer default or verification for policy, request construction for upload, and re-fetching identifiers for lookup.

Authentication errors

A forbidden error returns HTTP 403 and means the authorization layer blocked the request. Common causes are a missing youtube.upload scope, an expired access token, or a user who no longer owns the channel. The fix is to reconnect with the full upload scope set and confirm the authenticated user still owns the target channel. youtubeSignupRequired returns HTTP 401 and means the Google account is not linked to a YouTube channel. This happens when a Google account that has never created a channel is used, or when a Service Account is used instead of a user flow. Use OAuth 2.0 user flow and have the user create a channel first. insufficientPermissions returns HTTP 403 and means token scopes do not cover the requested operation, for example when only youtube.readonly was granted but an upload endpoint was called. Reconnect with youtube.upload and youtube scopes so the granted scopes match the operation.

Quota errors

quotaExceeded returns HTTP 403 and is the error to check first when uploads suddenly stop. YouTube Data API v3 projects have a default 10,000-unit daily quota, and a single upload costs 1,600 units, so a modest pipeline can consume the budget quickly. The remedies are to apply for a quota increase in the Google Cloud Console or to split workloads across multiple projects. uploadLimitExceeded returns HTTP 400 and means the account hit YouTube's per-user upload cap, which is especially restrictive for new or unverified channels. Verify the channel via phone number to raise the cap; otherwise wait 24 hours before retrying. A practical diagnostic order is: confirm quotaExceeded versus uploadLimitExceeded, estimate how many uploads the daily budget can support at 1,600 units each, then check scopes and required fields so a quota fix is not masked by a request error.

Metadata errors

invalidCategoryId returns HTTP 400 when snippet.categoryId is not a valid YouTube category. Category IDs are region-specific, so an ID that works in one region may not apply in the target region. Call videoCategories.list for the target region to fetch valid IDs. invalidTitle returns HTTP 400 when the title is empty, too long, or contains banned characters. YouTube caps titles at 100 characters and disallows characters such as < and >. Trim the title and strip disallowed characters before submitting. invalidDescription returns HTTP 400 when description validation fails. YouTube caps descriptions at 5,000 characters and disallows < and >. Trim or sanitize the description to fit the limit. The local preflight validator in the code example below applies these title, description, category, privacy, and file checks before any network call, which makes it a useful first step when metadata errors repeat.

Policy errors

forbiddenPrivacySetting returns HTTP 403 when a privacy setting is not allowed for the account or video. Some accounts cannot publish unlisted or public content without verification, and brand accounts have extra restrictions. Verify the channel or use private as the safe default. forbiddenLicenseSetting returns HTTP 403 when the license type is not allowed for the channel. A Creative Commons license requires channel eligibility and partner program status, so use the standard YouTube license when eligibility is not confirmed. authenticatedUserAccountSuspended returns HTTP 403 when YouTube has suspended the user's account. Suspended accounts cannot use the API at all, and the account owner must appeal in YouTube Studio; there is no programmatic recovery. Treat this code as a stop condition rather than a retryable error.

Upload errors

mediaBodyRequired returns HTTP 400 when the upload request did not include a video file. This usually means the multipart upload was malformed or the file stream was empty. Use resumable uploads for anything over 5MB and verify the file stream is non-empty before submitting. missingRequiredParameter returns HTTP 400 when a required field is missing. Common omissions are snippet.title, snippet.categoryId, and status.privacyStatus. Cross-check the request against the videos.insert reference and supply each required field explicitly. Before retrying an upload, run the preflight checks in order: file present and non-empty, title present and within limits, category ID fetched for the target region, and privacy status set.

Lookup errors

videoNotFound returns HTTP 404 when a video ID does not resolve. The video may have been deleted, may be private, or the ID may be wrong. Re-fetch the ID from the latest videos.list response instead of reusing a stored identifier. channelNotFound returns HTTP 404 when a channel ID is invalid or deleted. The channel may have been terminated by YouTube or the ID may never have been valid. Reconnect to fetch the current channel ID for the user. Lookup errors are usually stale-identifier problems, so the fix is to refresh the identifier from a fresh list or connection response and then retry the original operation.

Quick reference and recovery decisions

Use the quick-reference table below to find an error code with Ctrl/Cmd-F, then read the matching category section for the cause and fix. For decision-making, separate errors into three groups. Programmatically recoverable errors include metadata validation, missing parameters, missing media, scope mismatches, and stale identifiers; fix the request or reconnect and retry. Budget or verification errors include quotaExceeded, uploadLimitExceeded, forbiddenPrivacySetting, and forbiddenLicenseSetting; they need a quota increase, channel verification, a safer default, or waiting. Non-recoverable errors include authenticatedUserAccountSuspended and terminated channels; they require an account appeal or a new channel connection rather than another API retry.

Failure matrix: all 15 documented YouTube API errors
CodeHTTP statusCategoryWhat it meansFirst fix
forbidden403AuthenticationRequest blocked by authorization layer.Reconnect with the full upload scope set; confirm channel ownership.
youtubeSignupRequired401AuthenticationGoogle account is not linked to a YouTube channel.Use OAuth 2.0 user flow; create a channel first.
insufficientPermissions403AuthenticationToken scopes do not cover the requested operation.Reconnect with youtube.upload and youtube scopes.
quotaExceeded403QuotaDaily YouTube API quota consumed.Apply for a quota increase or split workloads across projects.
uploadLimitExceeded400QuotaAccount hit YouTube's per-user upload cap.Verify the channel via phone number; otherwise wait 24h.
invalidCategoryId400Metadatasnippet.categoryId is not a valid YouTube category.Call videoCategories.list for the target region.
invalidTitle400MetadataTitle is empty, too long, or has banned characters.Trim to 100 characters and strip < and >.
invalidDescription400MetadataDescription failed validation.Trim to 5,000 characters and strip < and >.
forbiddenPrivacySetting403PolicyPrivacy setting is not allowed for this account/video.Verify the channel or use private as the safe default.
forbiddenLicenseSetting403PolicyLicense type is not allowed for this channel.Use the standard YouTube license.
authenticatedUserAccountSuspended403PolicyYouTube suspended the user's account.Account owner must appeal in YouTube Studio.
mediaBodyRequired400UploadUpload request did not include a video file.Verify the file stream; use resumable uploads over 5MB.
missingRequiredParameter400UploadA required field is missing from the request.Cross-check against videos.insert; supply snippet.title, snippet.categoryId, and status.privacyStatus.
videoNotFound404LookupVideo ID does not resolve.Re-fetch the ID from the latest videos.list response.
channelNotFound404LookupChannel ID is invalid or deleted.Reconnect to fetch the current channel ID.

Documented error codes from the source page; fixes are the stated remedies for each code.

Upload request field map
FieldRequiredLimit or ruleError if violated
snippet.titleYesMaximum 100 characters; disallows < and >invalidTitle or missingRequiredParameter
snippet.categoryIdYesMust be a valid category ID for the target region; fetch via videoCategories.listinvalidCategoryId or missingRequiredParameter
status.privacyStatusYesMust be allowed for the account; private is the safe defaultmissingRequiredParameter or forbiddenPrivacySetting
DescriptionNoMaximum 5,000 characters; disallows < and >invalidDescription
Video file streamYesMust be present and non-empty; use resumable uploads over 5MBmediaBodyRequired

Field limits and requiredness are as documented in the source page.