Twilio error 31204 means the JWT access token passed to the Voice SDK during Device initialization is structurally invalid or contains claims that do not meet Twilio's requirements for a Voice access token. This is different from 31202 and 31205, which are about token expiry: 31204 fires when the token itself is malformed, uses the wrong signing key, lacks required claims, or has an incorrect claim value. The error fires synchronously during Device initialization.
What Causes This Error
Generating the access token using the wrong API Key Secret, which causes the JWT signature to be invalid when Twilio attempts to verify it against the registered API Key, is the most common cause. The token header and payload may decode correctly, but the signature check fails and Twilio rejects the token with 31204. Omitting the required grants claim from the token payload, or including the Voice grant with incorrect parameters such as a missing incoming.allow claim or an incorrect push_credential_sid, produces a token that is structurally a valid JWT but fails Twilio's semantic validation for Voice tokens. Passing the API Key SID as the AccountSid in the iss (issuer) claim instead of using the AccountSid for iss and the API Key SID for the sub (subject) claim is a common developer mistake that generates a structurally invalid Twilio access token. Concatenation errors in server-side code that build the token string manually rather than using the official Twilio helper library can produce a JWT with an incorrect number of base64url-encoded segments or padding issues.
How to Fix It Step by Step
Decode the JWT token your server is generating by splitting it on periods and base64url-decoding the header and payload segments (a tool like jwt.io can do this in the browser), then verify the payload contains: iss set to your AccountSid (starts with AC), sub set to your AccountSid, jti set to a unique identifier, exp set to a future Unix timestamp, and grants containing a voice object with incoming.allow set to true. Compare the API Key SID in your token generation code against the API Key listed in Console, then Settings, then API Keys to confirm it starts with SK and matches exactly: mismatches mean the signing key does not match what Twilio expects for that API Key SID. Use the official Twilio helper library's AccessToken class to regenerate the token: const token = new AccessToken(accountSid, apiKeySid, apiKeySecret, { ttl: 3600 }); const grant = new VoiceGrant({ incomingAllow: true }); token.addGrant(grant); token.identity = identity;, which handles all claim formatting correctly. Pass the regenerated token directly to new Device(token) and verify that Device initialization completes without a 31204 error before integrating the token endpoint into your application.
How to Prevent It from Recurring
Use the official Twilio server-side helper library (twilio-node, twilio-python, twilio-ruby, or twilio-java) exclusively for token generation and never construct JWT strings manually, as the library handles all claim formatting, signing algorithm selection, and base64url encoding correctly. Add a server-side token validation step that decodes the generated token before returning it to the client and asserts the presence and format of all required claims (iss, sub, exp, jti, grants.voice), returning a 500 error if validation fails so the issue is caught server-side rather than client-side. Store your API Key SID and API Key Secret in environment variables with clear naming that distinguishes SID from Secret (for example, TWILIO_API_KEY_SID and TWILIO_API_KEY_SECRET) to prevent them from being confused and passed in the wrong parameter positions. Rotate API Keys on a scheduled basis and update all token generation code simultaneously, using a deployment pipeline that validates a test token after every credential rotation.
When to Call a Specialist
If your token decodes correctly and all claims appear valid but 31204 errors persist, the API Key used to sign the token may have been revoked in the Console under Settings, then API Keys, which causes all tokens signed with that key to fail validation immediately regardless of the token's content. A specialist can audit your API Key lifecycle and identify whether a key revocation is causing the failure, then assist with rotating to a new key and updating all dependent applications. You should also seek specialist help if you are building a multi-tenant platform that generates tokens for multiple customer identities and subaccounts, as the AccountSid in the iss and sub claims must match the account under which the call will be made, and cross-account token usage produces 31204.
Conclusion
Error 31204 is a JWT structural or claim validation failure that is fixed by regenerating the token using the official Twilio helper library with correct AccountSid, API Key SID, API Key Secret, and Voice grant parameters. 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.