Error 40102 de TikTok: token de acceso caducado
El error 40102 de TikTok indica que el token de acceso enviado con la petición caducó, y el endpoint debe llamarse con el token más reciente. Un token de acceso de la Accounts API dura un día. Para renovarlo, envía el refresh token a /tt_user/oauth2/refresh_token/ y repite la llamada. El refresh token en sí dura un año; después, el titular de la cuenta vuelve a autorizar la app.
easyCoexistence renueva por sí solo el token de TikTok de 24 horas con el refresh token, antes de que caduque, para que las llamadas desde Claude, ChatGPT o tu propio código salgan con uno vigente.
Código de retorno de TikTok para un token de acceso caducado; el endpoint debe llamarse con el más reciente.
Cuánto tiempo sigue válido un token de acceso de cuenta de TikTok de la Accounts API.
El valor expires_in, en segundos, del ejemplo de TikTok de un token de acceso recién emitido.
Cuánto tiempo sigue válido el refresh token; cuando caduca, el titular debe volver a autorizar la app.
¿Qué significa el error 40102?
El token de acceso enviado en la cabecera Access-Token ha superado su fecha de caducidad. El apéndice de códigos de retorno de TikTok clasifica el 40102 como token de acceso caducado e indica que el endpoint debe llamarse con el más reciente. Su solución es usar un token de acceso válido y reintentar.
El código llega en el cuerpo de la respuesta. La mayoría de las llamadas a la API for Business de TikTok devuelven HTTP 200, y es el código de retorno, no el estado, el que indica si la llamada tuvo éxito.
¿Cuánto dura un token de acceso de TikTok?
Un día en la API for Business. La Accounts API emite un token de acceso de cuenta de TikTok cuando la app intercambia un código de autorización en /tt_user/oauth2/token/, y la respuesta indica su duración en expires_in: 86,400 segundos en el ejemplo de TikTok. La misma respuesta incluye un refresh token, válido un año, que TikTok recomienda conservar para renovar el token de acceso. Los user access tokens de TikTok for Developers, que usa la Content Posting API, duran en cambio 2 horas.
¿Cómo se renueva?
Envía el refresh token a /tt_user/oauth2/refresh_token/ con el ID y el secreto de la app y grant_type con el valor refresh_token. La respuesta trae un nuevo token de acceso y un nuevo refresh token: guarda ambos, envía a partir de entonces el nuevo token de acceso en la cabecera Access-Token y repite la llamada que falló. Renovarlo antes de que termine el día evita que las llamadas lleguen a TikTok con un token caducado.
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_in¿Cuándo tiene que volver a autorizar el titular?
Cuando ya no es posible renovar. El refresh token es válido un año, y la documentación de TikTok indica que, una vez vencido, el desarrollador pide al titular de la cuenta que vuelva a autorizar la app mediante el flujo de autorización. El titular también puede revocar la autorización en cualquier momento desde la app de TikTok, en Ajustes y privacidad, Seguridad, Gestionar permisos de apps, y una nueva autorización es entonces la vía de vuelta.
Errores comunes
- Renovar solo después de que falle una llamada. Un token que dura un día caduca cada día, así que renuévalo con antelación y evita que las llamadas lleguen a TikTok con uno antiguo.
- Ignorar el refresh token de la respuesta de renovación. La referencia de TikTok indica conservarlo para la siguiente renovación, así que guarda el que devuelve cada renovación.
- Revisar solo el estado HTTP. TikTok suele responder con HTTP 200 y pone el 40102 en el campo code, así que una comprobación del estado da por bueno un fallo.
- Guardar copias del token en varios sitios. Renovar una copia deja que las demás lleguen al final de su día y fallen con 40102.
Si TikTok rechaza el token igualmente con 40102, 40104 o 40105, la conexión se marca al instante para reconectar y recibes un correo. Tu código puede obtener el token actual desde get_social_credentials en lugar de guardar una copia. De US$ 9 a US$ 0.75 por conexión al mes, bajando a medida que añades conexiones, con los primeros 3 días gratis.
Preguntas frecuentes
¿Qué significa expires_in en una respuesta de token de TikTok?
Son los segundos que faltan para que caduque el token de acceso: 86,400, es decir, un día, en el ejemplo de TikTok de un token nuevo de la Accounts API. Súmalos a la hora de la respuesta para saber cuándo renovar, antes del 40102.
¿Se puede renovar un token de acceso de TikTok caducado?
Sí, mientras el refresh token sea válido. Envíalo a /tt_user/oauth2/refresh_token/, y TikTok devuelve un nuevo token de acceso con un refresh token.
¿El error 40102 significa que hay que reconectar la cuenta?
No por sí solo. Un refresh token válido renueva el acceso sin que intervenga el titular; hace falta una nueva autorización solo cuando el refresh token ha caducado o el titular ha revocado el acceso.
¿Por qué una respuesta con HTTP 200 contiene el error 40102?
Los códigos de retorno de TikTok tienen prioridad sobre el estado HTTP. Una llamada solo se considera exitosa si su código es 0, sea cual sea la línea de estado.
Sigue leyendo
Conecta tu primer canal en dos minutos.
Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.
- 3 días gratis
- Cancela cuando quieras
- Solo APIs oficiales
- Monitorizado 24/7
Verificado el