Twilio error 31205 fires when the JWT access token passed to the Voice SDK is valid in structure and claims but its exp (expiration) timestamp has already passed at the moment Twilio validates it during signaling. While 31202 typically surfaces when a token expires during an active SDK session, 31205 most commonly fires at Device initialization or re-registration when a cached or stale token is presented. Both errors have the same root fix: generate fresh tokens close to their point of use.
What Causes This Error
Caching the access token in client-side storage (localStorage, sessionStorage, or a JavaScript variable) without checking its expiry time before reusing it on page reload causes 31205 when the user returns to the page after the token has expired. Server-side token endpoint responses cached by a CDN or reverse proxy can serve the same expired token to new users who load the page after the token's TTL has passed, since the CDN does not understand the JWT exp claim. Generating access tokens with a short TTL (for example, 300 seconds / 5 minutes) for security reasons without implementing a corresponding client-side refresh mechanism guarantees that 31205 will occur for any user session that lasts longer than the TTL. A backend token generation job that pre-generates tokens in bulk (for example, a scheduled job that creates tokens for all agents at the start of a shift) and stores them for later retrieval will produce expired tokens if the delay between generation and first use exceeds the TTL.
How to Fix It Step by Step
When retrieving a cached token (from localStorage or a server-side cache), decode the JWT payload by splitting on '.' and base64-decoding the second segment, then compare the exp value (a Unix timestamp in seconds) against Date.now() / 1000 and discard the token if it is within 300 seconds of expiry. Fetch a fresh token from your server-side token endpoint immediately before initializing the Device rather than relying on a previously stored token: the token endpoint call should happen in the same function that calls new Device(token), ensuring freshness. Set Cache-Control: no-store, no-cache on your token endpoint HTTP response headers to prevent CDNs, browsers, and reverse proxies from caching token responses and serving stale tokens to subsequent requests. If pre-generating tokens is a business requirement (for example, for agent desktop applications), set the TTL to a value that exceeds the maximum time between generation and use, and implement a server-side token validity check that regenerates tokens within 10 minutes of their expiry.
How to Prevent It from Recurring
Generate access tokens on demand, never in bulk or in advance: call your token endpoint immediately before each Device initialization and each Device.updateToken() call, so the token is always fresh. Implement a token refresh scheduler that runs on a timer set to fire at 80 percent of the TTL value: for a 3600-second TTL, set a 2880-second timer that fetches a new token and calls Device.updateToken() proactively, long before the current token expires. Add a token expiry display to your developer console logging so that every token generation logs its expiry time in human-readable format, making it easy to verify during debugging that tokens have the expected TTL. For server-side token caching where multiple requests are served from a single generated token, include the token's exp timestamp as a server-side cache key expiry and regenerate the token 60 seconds before its exp time to ensure cached tokens never reach their expiry.
When to Call a Specialist
If 31205 errors occur immediately after token generation and the token's exp timestamp looks correct in the JWT payload, check for server clock skew: if your token generation server's clock is ahead of UTC, the token will appear to have expired immediately from Twilio's perspective if the skew exceeds a few minutes. A specialist can audit your server's NTP synchronization configuration and recommend monitoring to detect and alert on clock drift. You should also seek specialist help if you are building a high-availability system where token generation is distributed across multiple servers and you are seeing intermittent 31205 errors that correlate with specific server instances, as one server may have a clock synchronization issue that the others do not.
Conclusion
Error 31205 is a stale token error that is fixed by generating access tokens on demand immediately before use and implementing a proactive refresh cycle that keeps the Device's token current throughout the session. If this error is blocking your production system, contact our team and we will diagnose and fix it within the hour.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.