Errors

MCPTube error codes on MCP and the REST API: invalid key, quota exhausted, plan limit, unavailable video, YouTube blocks and the service being temporarily down.

On MCP, tool errors come back as a result with isError: true and the message in the text; transport errors use HTTP status codes and JSON-RPC codes. On the REST API, the body is always {"error": {"code", "message"}}, with stable codes you can handle in your code.

Situation	REST	Counts toward quota
Invalid, revoked or expired key or token	`401` `unauthorized`	No
Invalid parameter	`400` `invalid_request`	No
Invalid URL or playlist	`400` `invalid_url`	No
Missing, private or unavailable video	`404` `video_unavailable`	No
Plan refusal: length, AI transcription outside Pro or monthly cap	`403` `plan_limit`	Yes
IP blocked for abuse	`403` `banned`	No
Daily quota used up	`429` `quota_exceeded`	No
Too many failed attempts in a short time	`429` `failures_exceeded`	No
YouTube refused the server	`503` `youtube_blocked`	No
Service unavailable (database)	`503` `service_unavailable`	No
Internal error	`500` `internal`	No

On MCP, calls without credentials work on the anonymous plan. The 401 with the WWW-Authenticate header, which starts the OAuth login, comes with invalid credentials, with ?login=1 or when a request goes beyond the anonymous plan.

429 Too Many Requests (REST)

{
  "error": {
    "code": "quota_exceeded",
    "message": "Daily limit of 20 calls reached. The quota resets at 0h UTC. Your plan: Free. The Pro plan has higher limits and AI transcription: https://mcptube.com/en"
  }
}

Result with isError (MCP)

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Error: Daily limit of 20 calls reached. The quota resets at 0h UTC. Your plan: Free. The Pro plan has higher limits and AI transcription: https://mcptube.com/en"
  }]
}

On 503, wait a few seconds and repeat the call. If a Retry-After header comes back, wait that long.