Best Practices - BloxCord V3

The Game API is fast, but every call is a network request that shares a per-server budget. A few habits keep your experience responsive and prevent your calls from being throttled or dropped. Read this once before shipping.

Respect the rate limits

Every operation — single calls, batched calls, and reads — draws from one per-server budget:

Limit	Value
Operations per minute (per server)	120
Operations per `apiBatch`	20

When you exceed the budget, calls start returning nil/false (HTTP 429). Some expensive methods also carry their own, tighter limit — for example getLeaderboard allows one call every 30 seconds per server. These are noted on the relevant method.

Budgets are per game server, not per player. In a full 50-player server, “one call per player” can blow the entire minute budget in seconds. Always think in terms of the whole server.

Don’t call the same endpoint repeatedly

The single biggest cause of throttling is re-fetching data that hasn’t changed. Fetch it once, keep the result, and reuse it.

Never put an API call inside a loop that runs every frame or tick — a RunService.Heartbeat/Stepped/RenderStepped connection, a while true loop, or a per-hit combat handler. Even a “cheap” read will exhaust the budget and stall the calling thread (every call yields).

Fetch on the event that actually changes the data instead:

local BloxCord = game:WaitForChild("BloxCord")

-- GOOD: fetch a player's permissions once, when they join.
game.Players.PlayerAdded:Connect(function(player)
    local permissions = BloxCord:Invoke("getUserPermissions", player)
    player:SetAttribute("BC_Loaded", permissions ~= nil)
end)

-- BAD: re-fetching the same unchanging data on every command.
local function onCommand(player)
    local permissions = BloxCord:Invoke("getUserPermissions", player) -- ❌ every time
    -- ...
end

Cache reads in your own code

For data you read often, keep a small in-memory cache keyed by user id and refresh it only when it matters (on a timer, or after you change the underlying data).

local BloxCord = game:WaitForChild("BloxCord")

local cache = {}           -- [userId] = { data = ..., expires = os.clock() + ttl }
local TTL = 60             -- seconds

local function getProfile(userId)
    local entry = cache[userId]
    if entry and os.clock() < entry.expires then
        return entry.data
    end

    local profile = BloxCord:Invoke("getUserProfile", userId)
    if profile then
        cache[userId] = { data = profile, expires = os.clock() + TTL }
    end
    return profile
end

game.Players.PlayerRemoving:Connect(function(player)
    cache[player.UserId] = nil -- evict on leave
end)

A few methods are already cached for you per player for the length of their session — getUserPermissions and getUserRoles. You still shouldn’t call them in a loop, but you don’t need to build your own cache for them.

If you need to perform several operations at once, send them together with apiBatch instead of firing many separate calls. One batch of 20 counts the same against the budget as 20 singles, but it’s a single round-trip — faster, and far less likely to interleave with other work.

local BloxCord = game:WaitForChild("BloxCord")

-- One request instead of three.
local results = BloxCord:Invoke("apiBatch", host, {
    { op = "points.update",   args = { userId = "111", amount = 5, reason = "Attendance" } },
    { op = "points.update",   args = { userId = "222", amount = 5, reason = "Attendance" } },
    { op = "logbook.create",  args = { userId = "333", type = "warning", reason = "Late" } },
})

Award end-of-session points, mark attendees, and write logs in a single batch at the end rather than one call per player as things happen.

Debounce player-triggered actions

Any call a player can trigger (a button, a command, a chat trigger) needs a guard, or a single player can spam your budget. Track a per-player timestamp and reject calls that come too fast.

local lastUsed = {} -- [userId] = os.clock()
local COOLDOWN = 3  -- seconds

local function handleRequest(player)
    local now = os.clock()
    if lastUsed[player.UserId] and now - lastUsed[player.UserId] < COOLDOWN then
        return -- ignore spam
    end
    lastUsed[player.UserId] = now

    -- safe to make the call here
end

Handle failures without hammering

A nil or false return can mean a rejection or a transient network issue. Always check the result before using it, and if you retry, back off — never retry in a tight loop.

local BloxCord = game:WaitForChild("BloxCord")

local function withRetry(fn, attempts)
    for i = 1, attempts do
        local result = fn()
        if result ~= nil and result ~= false then
            return result
        end
        task.wait(2 ^ i) -- 2s, 4s, 8s ... exponential backoff
    end
    return nil
end

local balance = withRetry(function()
    return BloxCord:Invoke("getUserPoints", requester, player)
end, 3)

Do not retry immediately or in a loop. If you were throttled, retrying instantly keeps you throttled and can starve every other call in the server.

Run independent calls concurrently — within reason

Because each call yields, running several independent calls sequentially adds up their wait times. Use task.spawn to overlap them — but don’t fan out hundreds at once, or you’ll hit the budget instantly.

-- Overlap a handful of independent lookups.
for _, player in ipairs(game.Players:GetPlayers()) do
    task.spawn(function()
        local mins = BloxCord:Invoke("getUserMinutes", player.UserId, {})
        player:SetAttribute("BC_Minutes", mins and mins.active or 0)
    end)
end

For a value you need for many users at once, prefer a method that returns them together (e.g. getLeaderboard with a userIds list) over one call per user.

Keep payloads small and reuse identifiers

Each operation’s args payload is capped at 24 KB. Send only what the method needs — don’t forward large tables or entire data models.
When you start a session, keep the returned sid and pass it to every follow-up call rather than fetching the session again to find it.
Remember timestamps are Unix epoch milliseconds (see Core Concepts → Timestamps); os.time() returns seconds, so multiply by 1000.

Quick checklist

No API calls inside per-frame or while true loops.

Reads that don’t change are cached (or fetched once on join).

Multiple operations are grouped into a single apiBatch.

Player-triggered actions are debounced.

Every result is checked for nil/false before use.

Retries use backoff, never a tight loop.

Next steps

Core Concepts

Actor object, return conventions, yielding, and the full rate-limit rules.

apiBatch

Run several operations in a single request.

​Respect the rate limits

​Don’t call the same endpoint repeatedly

​Cache reads in your own code

​Batch related operations

​Debounce player-triggered actions

​Handle failures without hammering

​Run independent calls concurrently — within reason

​Keep payloads small and reuse identifiers

​Quick checklist

​Next steps

Core Concepts

apiBatch

Respect the rate limits

Don’t call the same endpoint repeatedly

Cache reads in your own code

Batch related operations

Debounce player-triggered actions

Handle failures without hammering

Run independent calls concurrently — within reason

Keep payloads small and reuse identifiers

Quick checklist

Next steps