Service Usage Limitations

Limitations and Throttling Features

To ensure a stable and reliable ecosystem for all users, Epic Online Services (EOS) implements client request rate limiting and service usage quotas. The following sections detail the specific policies and usage limitations in effect at this time. In general, EOS usage quotas are set high enough that they should never be reached by proper usage of the SDK.

Client Request Throttling

Client request throttling works at the level of individual users or server instances, with the intention to limit the impact that any single user or server can have on others. When the EOS SDK detects that calls to the back-end service are coming in too rapidly, the local client will self-throttle by rejecting API calls with the EOS_TooManyRequests error code. As a failsafe, the back-end service has a similar feature and will reject requests from individual clients or hosted servers that have exceeded the maximum usage guidelines with an HTTP 429 (Too Many Requests) error response. The error response will include the Retry After HTTP header that contains the time after which the client can make a request again to the same service endpoint. The EOS SDK will report this as EOS_TooManyRequests, and will internally handle the retry logic with the time specified in the HTTP data.

Service Usage Quotas

To ensure that the backend services will always have necessary capacity readily available for titles, each service applies usage quotas on a per-deployment basis. This method works in parallel to client request throttling to limit the impact that an individual title can have on the overall EOS ecosystem. Depending on the service type, quotas are either fixed, or adjust based on the number of concurrent users (CCU) online for each deployment. All quotas apply equally to every product in the EOS ecosystem. The following quotas are currently in force, though service-specific values are subject to change. The intention behind the specific values in each quota is to ensure that correct integrations of the EOS SDK will never be throttled by the quota system.

Player Data Storage

The Player Data Storage Interface enables developers using EOS to save encrypted, user-specific, game-specific data to cloud servers. Data that you store through this interface is accessible to the user on any device where they can log in. The Player Data Storage Interface supports any file format; typical use cases would include saved games and replay data.

The service applies limits to both storage amounts and usage rates. Throttling enforces usage rate limitations, and the service can delete files to enforce storage space limitations. For example, uploading a file larger than the maximum individual file size will result in the service automatically deleting that file.

Usage Type

Limitation

Read or Write

1000 requests per minute

Maximum individual file size (see note below)

200 MB

Auto-delete file size

400 MB

Maximum individual folder size

400 MB

Maximum files per user

1000

If a user uploads a file exceeding the maximum individual file size, the user will be prevented from uploading additional files until that file is deleted. If the file exceeds the auto-delete file size, the service will delete it immediately following the upload.

Stats

The Stats Interface provides the ability for developers to manage users' stats for an application, which can include any statistical data that a developer wishes to track, such as the number of items collected, the player's fastest completion time for a level, the total number of victories or losses, or the number of times that a user has performed a certain action. You can use stats to determine when to unlock achievements and how to use rank users in leaderboards .

The following limits apply to the overall Stats system:

Feature

Limitation

Number of Stats

500 per deployment

Stat Name Length

256 characters

Max Stats Ingested Per Call

3000

Stats Ingestion is the endpoint of submitting stat changes to the service, and has a per-user rate limit. When a dedicated server submits stats on behalf of users, the per-user limits do not apply; in these cases, limits are based on the number of concurrent users (CCU) per deployment at that time.

Usage Type

Per-User Limit

Per-Deployment Limit

Ingest Stats

60 requests per minute, 500 stats per request

1 request per 5 CCU per minute

Get Stats by PlayerId

100 requests per minute

Get Stats by PlayerIds

100 requests per minute, 64 players per request, 25 stats per player

Create Stat

100 requests per minute

Delete Stat

100 requests per minute

Achievements

The Achievements Interface provides a way for developers to retrieve data about a player's achievements, unlock achievements for that player, and retrieve data about all of the achievements belonging to an application.

The following limits apply to a deployment's overall use of achievements:

Feature

Limitation

Total number of achievements

1000

Stats per achievement

3

Achievement ID length

256 characters

Localized text variations per achievement

19

Localized text length

256 characters

There are also usage-rate limitations that apply on a per-user or per-deployment basis. Per-user limitations apply to individual users playing games and interacting with existing achievements, while per-deployment limitations apply to calls that set up the achievements that players can see and unlock.

Feature

Per-User Limitation

Per-Deployment Limitation

Get all achievement definitions

10 requests per minute

Get one achievement definition

100 requests per minute

Get a player's achievements

100 requests per minute

Unlock an achievement

100 requests per minute

Create Achievement

100 requests per minute

Delete Achievement

100 requests per minute

Leaderboards

The Leaderboards Interface gives developers using EOS the ability to rank scores from their entire player base, so that players can compete with their friends or other players worldwide for the top score. Each game can support multiple leaderboards, collecting scores from different sources, and ranking them with different scoring modes.

The following limits apply to a deployment's overall use of leaderboards:

Feature

Limitation

Number of global leaderboards

100

Number of friend leaderboards

Unlimited, see Stats for more details.

Friend leaderboards are made by directly querying Stats; they are not affected by the global leaderboard limit.

There are also usage-rate limitations that apply on a per-user or per-deployment basis. Per-user limitations apply to individual users playing games and viewing existing leaderboards, while per-deployment limitations apply to calls that create or delete those leaderboards.

Feature

Per-User Limitation

Per-Deployment Limitation

Get a single leaderboard value

100 requests per minute

Get all leaderboard values

10 requests per minute

Create a leaderboard

100 requests per minutes

Delete a leaderboard

100 requests per minutes

Sessions and Matchmaking

EOS gives players the ability to host, find, and interact with online gaming sessions through the Sessions Interface . A session can be short, like filling a certain number of player slots before starting a game, then disbanding after the game ends, or it could be longer, like keeping track of a game that cycles through matches on multiple maps or levels. The Sessions Interface also manages game-specific data that supports the back-end service's searching and matchmaking functionality.

The following limitations apply to sessions in general:

Feature

Limitation

Concurrent players

1000 per session

Session attributes

100 per session

Attribute name length

1000 characters

User interaction with the Sessions Interface must respect the following limitations:

Feature

Limitation

Per-Deployment Limitation

Create a session

30 requests per minute

30 request per 1 CCU per minute

Delete a session

30 requests per minute

30 request per 1 CCU per minute

Update a session

30 requests per minute

30 request per 1 CCU per minute

Add or remove players

100 requests per minute

30 request per 1 CCU per minute

Start or stop a session

30 requests per minute

30 request per 1 CCU per minute

Invite a user

100 requests per minute

30 request per 1 CCU per minute

Filter sessions

30 requests per minute

30 request per 1 CCU per minute

Lobbies

Lobbies provide a persistent connection between users, hosted by EOS, for the purpose of sharing game and user state with real-time updates. Typically, users can create or join lobbies to chat with other users, form teams, select pre-game options, and wait for additional players to join in before playing together. The EOS SDK supports this feature with the Lobby Interface . Using the Lobby Interface, your users can create, join, leave, and manage lobbies.

The following are general limitations for the lobby service:

Feature

Service Limit

Max players in a lobby

64

Max session attributes

100

Max member attributes

100

String attribute length

1000 characters

There are also per-user rate limitations. Observe the following limitations to avoid throttling:

Feature

User Limit

Connect

30 requests per minute

Create a lobby

30 requests per minute

Delete a lobby

30 requests per minute

Join a lobby

30 requests per minute

Read lobby data

100 requests per minute

Update lobby attributes

100 requests per minute

Update member attributes

100 requests per minute

Change lobby settings

30 requests per minute

Invite a user

30 requests per minute

Delete an invitation

30 requests per minute

Kick a player out

30 requests per minute

Promote a member to lobby owner

30 requests per minute

Find lobbies

30 requests per minute

Get a lobby by ID

100 requests per minute

Find lobbies by user

30 requests per minute

Find invitations by user

30 requests per minute

Find lobby by invitation

30 requests per minute

Best Practices

When the SDK APIs are integrated correctly with the game code, the request limits and usage quotas should never be reached. However, to ensure that the game will operate smoothly in a live environment, it is good to be mindful of the limits and pay attention to the SDK's log output. During internal play testing, any erroneous log output should be checked to verify that EOS functions are not returning the EOS_TooManyRequests result or otherwise warning about incorrect use patterns.

As an example, if an EOS interface provides a listener function to receive events automatically, the game should use that function for updating its own cached data rather than using querying functions to poll the back-end service periodically. The Friends Interface is a good example of an interface where event updates can replace frequent queries.

We will be adding new analytics dashboards in DevPortal that enable developers to monitor back-end service usage patterns and highlight potential SDK integration issues that could trigger usage limiting to take place.