Erro 40102 do TikTok: access token expirado
O erro 40102 do TikTok significa que o access token enviado na requisição expirou, e o endpoint precisa ser chamado com o token mais recente. Um access token da Accounts API dura um dia. Renove-o enviando o refresh token para /tt_user/oauth2/refresh_token/ e repita a chamada. O próprio refresh token dura um ano; depois disso, o titular da conta autoriza o app de novo.
O easyCoexistence renova sozinho o token de 24 horas do TikTok com o refresh token, antes de expirar, para que as chamadas feitas pelo Claude, pelo ChatGPT ou pelo seu próprio código saiam com um token atual.
Código de retorno do TikTok para um access token expirado; o endpoint deve ser chamado com o mais recente.
Por quanto tempo um access token de conta do TikTok, emitido pela Accounts API, permanece válido.
O valor expires_in, em segundos, no exemplo do TikTok de um access token recém-emitido.
Por quanto tempo o refresh token permanece válido; quando ele expira, o titular precisa autorizar o app novamente.
O que significa o erro 40102?
O access token enviado no cabeçalho Access-Token passou da data de validade. O apêndice de códigos de retorno do TikTok lista o 40102 como access token expirado e diz que o endpoint precisa ser chamado com o mais recente. A correção é usar um access token válido e repetir a chamada.
O código vem no corpo da resposta. A maioria das chamadas à API for Business do TikTok retorna HTTP 200, e é o código de retorno, não o status, que indica se a chamada deu certo.
Por quanto tempo um access token do TikTok dura?
Um dia na API for Business. A Accounts API emite um access token de conta do TikTok quando o app troca um código de autorização em /tt_user/oauth2/token/, e a resposta informa a duração em expires_in, 86,400 segundos no exemplo do TikTok. A mesma resposta traz um refresh token, válido por um ano, que o TikTok recomenda guardar para renovar o access token. Os user access tokens do TikTok for Developers, usados pela Content Posting API, duram 2 horas.
Como renovar?
Envie o refresh token para /tt_user/oauth2/refresh_token/ com o ID e o secret do app e grant_type definido como refresh_token. A resposta traz um novo access token e um novo refresh token: guarde os dois, envie o novo access token no cabeçalho Access-Token daí em diante e repita a chamada que falhou. Renovar antes de o dia terminar evita que as chamadas cheguem ao TikTok com um token expirado.
curl -X POST 'https://business-api.tiktok.com/open_api/v1.3/tt_user/oauth2/refresh_token/' \
-H 'Content-Type: application/json' \
-d '{
"client_id": "<APP_ID>",
"client_secret": "<SECRET>",
"grant_type": "refresh_token",
"refresh_token": "<REFRESH_TOKEN>"
}'
# data: access_token, expires_in (86400), refresh_token, refresh_token_expires_inQuando o titular precisa autorizar de novo?
Quando a renovação não é mais possível. O refresh token é válido por um ano, e a documentação do TikTok diz que, depois que ele expira, o desenvolvedor pede ao titular da conta que autorize o app novamente pelo fluxo de autorização. O titular também pode revogar a autorização a qualquer momento no app do TikTok, em Configurações e privacidade, Segurança, Gerenciar permissões do app, e uma nova autorização é então o caminho de volta.
Erros comuns
- Renovar só depois que uma chamada falha. Um token que dura um dia expira todo dia, então renove antes e evite que as chamadas cheguem ao TikTok com um token antigo.
- Ignorar o refresh token da resposta de renovação. A referência do TikTok diz para guardá-lo para a próxima renovação, então salve o que cada renovação devolver.
- Verificar só o status HTTP. O TikTok costuma responder com HTTP 200 e coloca 40102 no campo code, então uma checagem apenas do status lê a falha como sucesso.
- Manter cópias do token em vários lugares. Renovar uma cópia deixa as outras chegarem ao fim do dia e falharem com 40102.
Se o TikTok rejeitar o token mesmo assim com 40102, 40104 ou 40105, a conexão é marcada para reconexão na hora e você recebe um e-mail. Seu código pode buscar o token atual em get_social_credentials, em vez de guardar uma cópia. De US$ 9 a US$ 0.75 por conexão por mês, caindo conforme você adiciona conexões, com os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
O que significa expires_in em uma resposta de token do TikTok?
É o número de segundos até o access token expirar: 86,400, um dia, no exemplo do TikTok para um novo token da Accounts API. Some esse valor ao horário da resposta para saber quando renovar, antes do 40102.
Um access token expirado do TikTok pode ser renovado?
Sim, enquanto o refresh token for válido. Envie-o para /tt_user/oauth2/refresh_token/, e o TikTok devolve um novo access token com um refresh token.
O erro 40102 significa que a conta precisa ser reconectada?
Não por si só. Um refresh token válido renova o acesso sem o titular; uma nova autorização só é necessária quando o refresh token expirou ou o titular revogou o acesso.
Por que uma resposta com HTTP 200 contém o erro 40102?
Os códigos de retorno do TikTok têm precedência sobre o status HTTP. Uma chamada só deu certo se o código for 0, qualquer que seja a linha de status.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em