YouTube Data API v3

YouTube API Errors

YouTube Data API errors for uploads, metadata, and quota — including the dreaded quotaExceeded.

YouTube's API is unusual in that the largest source of failures is the daily quota — a single upload costs 1,600 units of a 10,000-unit default budget.

PostPeer YouTube API View Docs

Authentication3 Quota2 Metadata3 Policy3 Upload2 Lookup2

Authentication

3 errors in this category

forbiddenHTTP 403Authentication

Request blocked by authorization layer.

Why it happens: Missing OAuth scopes (need `youtube.upload`), expired access token, or the user no longer owns the channel.
How to fix: Reconnect with the full upload scope set. PostPeer refreshes Google OAuth tokens automatically.

youtubeSignupRequiredHTTP 401Authentication

Google account is not linked to a YouTube channel.

Why it happens: You authenticated a Google account that has never created a YouTube channel, or used a Service Account.
How to fix: Use OAuth 2.0 user flow and have the user create a channel at studio.youtube.com first.

insufficientPermissionsHTTP 403Authentication

Token scopes do not cover the requested operation.

Why it happens: Granted only `youtube.readonly` but called an upload endpoint, or similar mismatch.
How to fix: Reconnect with `youtube.upload` and `youtube` scopes.

Quota

2 errors in this category

quotaExceededHTTP 403Quota

Daily YouTube API quota consumed.

Why it happens: YouTube Data API gives projects a default 10,000-unit daily quota. A single upload costs 1,600 units, so even a modest pipeline burns through it fast.
How to fix: Apply for a quota increase in the Google Cloud Console, or split workloads across multiple projects.
How PostPeer handles it: PostPeer pools quota across customer projects and falls back to slower channels rather than failing publishes.

uploadLimitExceededHTTP 400Quota

Account hit YouTube's per-user upload cap.

Why it happens: YouTube limits uploads per channel per day, especially for new or unverified channels.
How to fix: Verify the channel via phone number to raise the cap; otherwise wait 24h.

Metadata

3 errors in this category

invalidCategoryIdHTTP 400Metadata

`snippet.categoryId` is not a valid YouTube category.

Why it happens: Category IDs are region-specific. The ID you sent does not apply in the target region.
How to fix: Call `videoCategories.list` for the target region to fetch valid IDs.

invalidTitleHTTP 400Metadata

Title is empty, too long, or has banned characters.

Why it happens: YouTube caps titles at 100 characters and disallows certain characters like `<` and `>`.
How to fix: Trim and strip disallowed characters.
How PostPeer handles it: PostPeer validates titles at API boundary so this never reaches YouTube.

invalidDescriptionHTTP 400Metadata

Description failed validation.

Why it happens: YouTube caps descriptions at 5,000 characters and disallows `<` and `>`.
How to fix: Trim or sanitize the description.

Policy

3 errors in this category

forbiddenPrivacySettingHTTP 403Policy

Privacy setting is not allowed for this account/video.

Why it happens: Some accounts cannot publish unlisted/public content without verification; brand accounts have extra restrictions.
How to fix: Verify the channel or use `private` as the safe default.

forbiddenLicenseSettingHTTP 403Policy

License type is not allowed for this channel.

Why it happens: Creative Commons license requires channel eligibility and partner program status.
How to fix: Use the standard YouTube license.

authenticatedUserAccountSuspendedHTTP 403Policy

YouTube suspended the user's account.

Why it happens: Policy enforcement — suspended accounts can't use the API at all.
How to fix: Account owner must appeal in YouTube Studio. No programmatic recovery.

Upload

2 errors in this category

mediaBodyRequiredHTTP 400Upload

Upload request did not include a video file.

Why it happens: Multipart upload was malformed or the file stream was empty.
How to fix: Use resumable uploads for anything over 5MB; verify the file stream before submitting.

missingRequiredParameterHTTP 400Upload

A required field is missing from the request.

Why it happens: Common omissions: `snippet.title`, `snippet.categoryId`, or `status.privacyStatus`.
How to fix: Cross-check against `videos.insert` reference. PostPeer fills sane defaults so you can publish with just a title.

Lookup

2 errors in this category

videoNotFoundHTTP 404Lookup

Video ID does not resolve.

Why it happens: Video was deleted, is private, or the ID is wrong.
How to fix: Re-fetch the ID from the latest `videos.list` response.

channelNotFoundHTTP 404Lookup

Channel ID is invalid or deleted.

Why it happens: Channel was terminated by YouTube or the ID was never valid.
How to fix: Reconnect to fetch the current channel ID for the user.

Quick reference

All 15 YouTube errors in one table — Ctrl/Cmd-F to find yours.

Code	Category	What it means
quotaExceeded	Quota	Daily YouTube API quota consumed.
uploadLimitExceeded	Quota	Account hit YouTube's per-user upload cap.
forbidden	Authentication	Request blocked by authorization layer.
youtubeSignupRequired	Authentication	Google account is not linked to a YouTube channel.
insufficientPermissions	Authentication	Token scopes do not cover the requested operation.
invalidCategoryId	Metadata	`snippet.categoryId` is not a valid YouTube category.
invalidTitle	Metadata	Title is empty, too long, or has banned characters.
invalidDescription	Metadata	Description failed validation.
forbiddenPrivacySetting	Policy	Privacy setting is not allowed for this account/video.
forbiddenLicenseSetting	Policy	License type is not allowed for this channel.
mediaBodyRequired	Upload	Upload request did not include a video file.
missingRequiredParameter	Upload	A required field is missing from the request.
videoNotFound	Lookup	Video ID does not resolve.
channelNotFound	Lookup	Channel ID is invalid or deleted.
authenticatedUserAccountSuspended	Policy	YouTube suspended the user's account.

Other platforms

Instagram errors

33 documented

X (Twitter) errors

12 documented

TikTok errors

25 documented

Facebook errors

15 documented

LinkedIn errors

9 documented

Bluesky errors

10 documented

Pinterest errors

8 documented

Threads errors

7 documented

Ready to Add Social Media to Your Product?

One API. Every platform. Start building with free credits.

Start Posting for FreeNo credit card required.

POST https://api.postpeer.dev/v1/posts
{ "platforms": ["twitter", "linkedin", "instagram], "content": "Hello world!" }

Published

5 platforms

TwitterLinkedInFacebook+2

All posts delivered

Scheduled

queue

Queued

847

Sent

Next: in 15 min

Platforms

connected

XIGFBLITT

One API, every platform