Erros

Códigos de erro do MCPTube no MCP e na API REST: chave inválida, cota esgotada, limite do plano, vídeo indisponível, bloqueio do YouTube e serviço fora do ar.

No MCP, erros de ferramenta voltam como resultado com isError: true e a mensagem no texto; erros de transporte usam status HTTP e códigos JSON-RPC. Na API REST, o corpo é sempre {"error": {"code", "message"}}, com códigos estáveis para tratar no seu código.

Situação	REST	Conta na cota
Chave ou token inválido, revogado ou vencido	`401` `unauthorized`	Não
Parâmetro inválido	`400` `invalid_request`	Não
URL inválida ou playlist	`400` `invalid_url`	Não
Vídeo inexistente, privado ou indisponível	`404` `video_unavailable`	Não
Recusa do plano: duração, transcrição por IA fora do Pro ou teto mensal	`403` `plan_limit`	Sim
IP bloqueado por abuso	`403` `banned`	Não
Cota diária esgotada	`429` `quota_exceeded`	Não
Muitas tentativas com erro em pouco tempo	`429` `failures_exceeded`	Não
O YouTube recusou o servidor	`503` `youtube_blocked`	Não
Serviço indisponível (banco de dados)	`503` `service_unavailable`	Não
Erro interno	`500` `internal`	Não

No MCP, a chamada sem credencial funciona no plano anônimo. O 401 com o cabeçalho WWW-Authenticate, que inicia o login OAuth, vem com credencial inválida, com ?login=1 ou quando um pedido passa do plano anônimo.

429 Too Many Requests (REST)

{
  "error": {
    "code": "quota_exceeded",
    "message": "Limite diário de 20 chamadas atingido. A cota reseta à 0h UTC. Seu plano: Gratuito. O plano Pro tem limites maiores e transcrição por IA: https://mcptube.com"
  }
}

Resultado com isError (MCP)

{
  "isError": true,
  "content": [{
    "type": "text",
    "text": "Erro: Limite diário de 20 chamadas atingido. A cota reseta à 0h UTC. Seu plano: Gratuito. O plano Pro tem limites maiores e transcrição por IA: https://mcptube.com"
  }]
}

Com 503, espere alguns segundos e repita a chamada. Se o cabeçalho Retry-After vier, respeite o tempo indicado.