Porque é que a ligação à API do TikTok deixa de funcionar e como a manter ativa
A ligação à API for Business do TikTok deixa de funcionar quando o seu token de acesso de 24 horas não é renovado, quando o refresh token de um ano expira, quando o titular da conta remove o acesso da aplicação ou quando o token enviado está em falta ou errado. O TikTok indica os casos de token com os códigos 40102, 40103, 40104 e 40105. Renovar antes do tempo, verificar cada conta de forma programada e pedir ao titular que autorize de novo antes de o ano terminar mantêm a ligação ativa.
A easyCoexistence mantém cada ligação ao TikTok viva por conta própria: renova o token de 24 horas com antecedência, verifica a conta cerca de cada 6 horas e, quando o TikTok recusa o token, marca o canal com Reconexão necessária e envia-lhe um email, seja para o Claude, o ChatGPT ou a sua própria plataforma.
Duração do token de acesso de uma conta TikTok na API for Business; /tt_user/oauth2/refresh_token/ renova-o.
Duração do refresh token; depois de expirar, o titular da conta tem de autorizar a aplicação outra vez.
Motivo de falha quando o titular remove o acesso da aplicação enquanto o TikTok processa uma publicação; o TikTok indica que não se deve repetir.
Eventos que o TikTok deixa de enviar para uma conta depois de a autorização do titular expirar ou ser revogada.
Motivo de disparo do authorization.removed no TikTok for Developers: o utilizador desliga a ligação, a conta é eliminada, a idade muda, há um banimento ou o programador revoga o acesso.
Frequência com que a easyCoexistence verifica cada conta TikTok ligada; renova o token de 24 horas por conta própria e envia-lhe um email se for preciso religar.
Porque é que a ligação à API do TikTok deixa de funcionar?
Por vários motivos, a maioria ligada aos tokens da conta ou ao consentimento do titular. Algumas terminam a ligação por completo; outras deixam-na a meio, com algumas chamadas recusadas e as restantes a continuar a responder:
Que erro devolve cada causa e como se resolve?
O campo code do TikTok identifica a maior parte delas, numa resposta HTTP 200 e não num estado de erro, e o estado de publicação acrescenta um motivo de falha próprio. O 40100 está na tabela porque uma chamada limitada pode parecer uma ligação perdida. O que cada um significa e a solução:
| What it means | The fix | |
|---|---|---|
| 40102 | The access token is past its 24 hours | Renew with the refresh token, store both new tokens, repeat the call |
| 40103 | The refresh token has expired | A new authorization by the owner; nothing renews it |
| 40104 | The request carried no access token | A bug in the request: send the Access-Token header |
| 40105 | The access token is invalid or incorrect | Check what was sent, renew, then ask the owner to authorize again |
| 40107 | The refresh token is invalid or incorrect | Send the refresh token from the latest response, or a new authorization |
| 40131 | Authentication failed at a token endpoint | Check the app ID and secret, then the code or the refresh token |
| 40001 | A permission or scope is missing | Add it to the app, then have the owner authorize again |
| auth_removed | Access was removed while a post was processing | No retry; publish again after a new authorization |
| 40100 | Throttled, not disconnected | Pause the endpoint 5 minutes; the token still works |
Quanto duram os tokens e quando se deve renovar?
Na API for Business, o token de acesso dura 24 horas, e expires_in em cada resposta de token indica os segundos que faltam; o refresh token dura um ano, com a sua própria contagem em refresh_token_expires_in. Renove bem antes de o dia terminar, de forma programada e não depois de uma chamada falhar, e guarde o refresh token que cada renovação devolve, já que a nota do TikTok sobre esse campo pede que seja conservado. Trate refresh_token_expires_in como um prazo: no exemplo de renovação do TikTok, conta para trás em vez de iniciar um novo ano.
O que acontece quando o titular remove o acesso da aplicação?
A aplicação perde as permissões da Accounts API que o titular concedeu, pelo que as chamadas com esse token deixam de funcionar, e o TikTok não documenta nenhum evento da API for Business que o anuncie. O titular pode fazê-lo a qualquer momento na aplicação TikTok, em Definições e privacidade, Segurança, Gerir as permissões da aplicação, Remover acesso. Os sinais aparecem noutro lado: uma publicação que o TikTok estava a processar falha com auth_removed, caso em que o TikTok indica que não se deve repetir, e os eventos comment.update da conta deixam de chegar.
O que faz uma mudança de tipo de conta à ligação?
O TikTok não associa nenhum erro de token a esta alteração nos seus documentos; o que muda é o que a API devolve. Dados como unique_video_views, daily_new_followers e audience_activity exigem Advanced Access ou uma Verified Business Account, tal como as Mentions and Business Messaging APIs, e o privacy_level_options de uma conta privada deixa de incluir PUBLIC_TO_EVERYONE. Desde 16 de outubro de 2026, is_business_account só devolve true para as Verified Business Accounts e has_advanced_access indica o Advanced Access, por isso ler os dois, em user.account.type, mostra uma alteração antes de uma chamada falhar por causa dela.
Como se detetam ligações inativas antes de o cliente o notar?
Com verificações que correm, haja ou não publicações:
- Uma chamada leve por conta, de forma programada, como /business/get/ com o campo username, que devolve um erro de token quando o token deixa de funcionar.
- /
tt_user/token_info/get/, que não exige permissão e devolve o âmbito do token, para confirmar que as permissões ainda cobrem o que as suas funcionalidades chamam. refresh_token_expires_inconvertido numa data a cada resposta recebida, com um lembrete ao titular algumas semanas antes.- Silêncio em comment.update numa conta que costuma receber comentários, já que o TikTok deixa de enviar esses eventos quando a autorização expira ou é revogada.
- 40102, 40103, 40104 e 40105 contados por conta, para que uma conta com falhas se destaque entre muitas.
Como se volta a ligar uma conta?
Com uma nova autorização para a mesma conta. Partilhe o URL de autorização do titular da conta TikTok, com um valor state que associe o regresso à conta, e disable_auto_auth=1 se o titular deve voltar a ver a página de permissões. Troque o novo auth_code em /tt_user/oauth2/token/ dentro dos seus 10 minutos e depois substitua os dois tokens guardados. open_id é o ID específico da aplicação que o TikTok atribui à conta, por isso associe os novos tokens ao registo guardado através dele, em vez de criar um segundo.
As ligações da Content Posting API expiram do mesmo modo?
Não. O TikTok for Developers, que disponibiliza as APIs Content Posting e Display, atualizou as suas páginas de tokens a 2 de novembro de 2026: os tokens de acesso de utilizador expiram em 2 horas e os refresh tokens duram 180 dias desde a primeira emissão. Os refresh tokens são rotativos, por isso cada renovação bem-sucedida devolve um novo e invalida de imediato o anterior, que foi enviado; se um servidor continuar a usar um token substituído, as renovações seguintes falham e o utilizador tem de autorizar de novo. Um refresh token inválido falha com invalid_grant, um token de acesso inválido com access_token_invalid e HTTP 401, e o webhook authorization.removed indica o motivo pelo qual um utilizador saiu.
O que faz a easyCoexistence para manter viva uma ligação ao TikTok?
Renova e verifica por conta própria, e avisa quando só o titular pode resolver:
- Renovação: antes de uma chamada quando faltam menos de 15 minutos, e durante uma verificação quando faltam menos de 8 horas, guardando de cada vez o novo refresh token e a respetiva validade.
- Uma renovação de cada vez por conta, para que as chamadas que chegam em simultâneo a partilhem.
- A verificação: uma chamada /business/get/ para o username da conta, cerca de cada 6 horas.
- Um token recusado, 40102, 40104 ou 40105: o canal fica com o estado Reconexão necessária, o titular recebe um email, e uma plataforma recebe channel.disconnected, com a mensagem do TikTok em
disconnected_reason. - Até lá, as ferramentas respondem que a conta precisa de ser religada, e uma publicação agendada falha com o estado reconnect em vez de chegar ao TikTok.
- Religação: Ligar o TikTok na página do canal, ou uma nova sessão de ligação, inicia sessão outra vez e mantém o mesmo
account_ide destino de eventos.
Como configurar
- Store both tokens with datesSave access_token, refresh_token, open_id and scope, and turn expires_in and refresh_token_expires_in into dates as each response arrives.
- Renew ahead of the dayCall /tt_user/oauth2/refresh_token/ well before the 24 hours end, one renewal per account at a time, and keep the refresh token it returns.
- Check each accountMake one light call per account on a schedule and record any 40102, 40103, 40104 or 40105 against that account.
- Ask before the year endsSend the owner the authorization URL before refresh_token_expires_in runs out, and replace both tokens when the new code arrives.
- Reconnect on a token errorWhen renewal fails or the token is refused, stop calling for that account and send its owner the authorization URL.
Erros comuns
- Tratar um webhook de comentários silencioso como uma conta silenciosa. O TikTok deixa de enviar comment.update para uma conta quando a autorização termina, por isso verifique a conta em vez de esperar por eventos.
- Religar para um registo novo. Associe os novos tokens pelo open_id, o ID específico da aplicação que o TikTok atribui à conta, e atualize o registo guardado, sem criar outro, mantendo o histórico e as definições.
- Repetir 40103 ou 40107 com o mesmo refresh token. Nenhum dos dois se resolve ao repetir: o primeiro exige uma nova autorização, e o segundo exige o refresh token da resposta mais recente ou uma nova autorização.
- Ler 40100 como uma ligação perdida. É uma chamada limitada; pause o endpoint 5 minutos, ou até às 00:00 UTC após um limite diário, e o mesmo token continua a funcionar.
De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias gratuitos.
Perguntas frequentes
Uma ligação à API do TikTok pode durar para sempre sem o titular?
Não. A renovação mantém-na até ao máximo de um ano do refresh token; depois disso, o caminho documentado pelo TikTok é uma nova autorização pelo titular da conta.
Porque falharam as ligações do TikTok em várias contas ao mesmo tempo?
Veja primeiro a aplicação e só depois as contas: o 40113 significa que a aplicação está bloqueada ou que o ID e o segredo não coincidem, e o TikTok pode revogar o acesso de uma aplicação à Accounts API por uso indevido.
Uma nova funcionalidade obriga a religar contas do TikTok?
Quando precisa de um âmbito que o titular nunca concedeu, sim. Um token mantém os âmbitos aprovados na autorização, por isso o titular volta a autorizar a aplicação para acrescentar um.
O que acontece às publicações agendadas no TikTok enquanto uma conta precisa de ser religada?
Na easyCoexistence, falham com o estado reconnect na hora agendada em vez de chegar ao TikTok, o titular recebe um email, e Repetir envia-as quando a conta voltar a estar ligada.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em