Issue

The CPS_UPSTREAM_PER_CONNECTION error may occur when using the Twilio Conversations Client JavaScript SDK to retrieve conversations with client.getSubscribedConversations().

Product

Twilio Conversations Classic

Environment

legacy Twilio Console

Cause

The CPS_UPSTREAM_PER_CONNECTION error occurs when using the Twilio Conversations Client JavaScript SDK, specifically when calling client.getSubscribedConversations() for users who are members of more than 1,000 conversations. In this scenario, the SDK attempts to subscribe the client to each conversation, resulting in a burst of upstream requests that exceeds the allowed per-connection rate limit. As a result, the error is triggered before the Paginator instance can be returned, preventing retrieval of the user's conversations.

Resolution

To avoid the CPS_UPSTREAM_PER_CONNECTION rate limit error, you can consider implementing the following best practices:

If enumeration in the client is required:

• Process one page at a time using getSubscribedConversations()
• Throttle any follow-on getConversationBySid(sid) calls to prevent request bursts

For optimal performance, use lazy-loading and throttling:

• List conversation SIDs via a backend process using the REST API 
• Only subscribe to a conversation when a thread is opened by calling getConversationBySid(sid)
• Cap the number of concurrent subscriptions (for example, no more than 5 at a time)
• Add a small delay or jitter between each subscription to avoid exceeding the rate limit

Additional Information

• The per-connection upstream limit for Twilio Conversations Classic is currently 500/s 
• REST API calls to list conversations do not trigger this error, as they do not initiate real-time subscriptions
• For more details on Conversations limits, refer to: Conversations Limits | Twilio