Sending feedback over HTTP

How a game's servers send player feedback straight to the feedback endpoint - what to send, what to do with each answer, retries and limits.

Building on the platform

A game that does not use the Template's platform service sends feedback itself, with HttpService:RequestAsync from a server script, to POST https://studio.blockoutgames.com/developer/v1/feedback. This page is the how-to; every field and status is on the reference page, POST /developer/v1/feedback.

Request

Send JSON with the game's key as Authorization: Bearer bk_live_… and Content-Type: application/json. The body holds an idempotencyKey (8 to 64 letters, digits, - or _), a category (bug, suggestion, balance, praise or other), the text (1 to 2,000 characters after trimming), the placeId, and optionally the player's playerId and a serverVersion (up to 64 characters). Any other field is refused, and the body may be at most 16 KiB. Field by field: The feedback body fields.

Answers

StatusWhat to do
202Stored. The body is the receipt, id and receivedAt
400Fix the body: error.issues names each field. Retrying the same body will not help
401The key is missing, wrong or revoked: check the secret, and stop sending
413The body is over 16 KiB: send less
429Wait the Retry-After seconds, then retry with the same body
5xxRetry with backoff (1, 2, 4 seconds), with the same body

Retries and idempotency

Make one idempotency key per piece of feedback (HttpService:GenerateGUID(false) fits) and send every retry of it with the same key. The platform stores it once and answers every retry with the first receipt, so a retry after a timeout never makes a duplicate. A retry that changes the text still gets the first receipt; the change is not stored. Retry only no answer, 429 and 5xx, a few times; give up on any other refusal.

A feedback retry after a timeout. The game server posts feedback with idempotency key K. The platform stores it, but the answer is lost and the server sees a timeout. The server posts the same body with the same key K again. The platform finds feedback already stored under K for this game, stores nothing, and answers 202 with the first receipt, the same id and receivedAt. One piece of feedback is stored.

The key is unique per game: two games may use the same idempotency key without clashing, and one game's keys are compared with its own feedback only.

A complete Luau sender with retries

For a game not built on the Template (a Template game has PlatformService.sendFeedback), this is a complete sender: one body and one idempotency key, up to four tries, waiting as long as a 429 asks or backing off after a 5xx or no answer, and stopping on any other refusal.

ServerScriptService/SendFeedback.luau
local HttpService = game:GetService("HttpService")local URL = "https://studio.blockoutgames.com/developer/v1/feedback"local MAX_TRIES = 4return function(player: Player, category: string, text: string): (boolean, any)	local found, authorization = pcall(function()		return HttpService:GetSecret("BlockoutApiKey"):AddPrefix("Bearer ")	end)	if not found then		return false, "the secret BlockoutApiKey is not set"	end	-- Encoded once, so every try carries the same idempotency key.	local body = HttpService:JSONEncode({		idempotencyKey = HttpService:GenerateGUID(false),		category = category,		text = text,		playerId = player.UserId,		placeId = game.PlaceId,		serverVersion = tostring(game.PlaceVersion),	})	for try = 1, MAX_TRIES do		local sent, response = pcall(function()			return HttpService:RequestAsync({				Url = URL,				Method = "POST",				Headers = { Authorization = authorization, ["Content-Type"] = "application/json" },				Body = body,			})		end)		if sent and response.Success then			return true, HttpService:JSONDecode(response.Body) -- { id, receivedAt }		end		local status = if sent then response.StatusCode else nil		if status and status < 500 and status ~= 429 then			return false, `refused ({status})` -- 400, 401, 413: retrying will not help		end		if try < MAX_TRIES then			local asked = if sent then tonumber(response.Headers["retry-after"]) else nil			task.wait(asked or 2 ^ (try - 1) + math.random())		end	end	return false, "no answer after every try"end

Call it in task.spawn: it yields while it waits. Check the category and length and limit each player before calling it (Checking what players send).

Limits

  • 120 requests a minute per key, for every server of the game together, shared with the market reads.

  • 1,200 a minute for every game's key together.

  • 240 writes a minute from one address, counted before the key is read.

Feedback is never cached: each send is one request, plus its retries. Limit how often each player may send before you call the endpoint; the Template allows one every 30 seconds and 10 an hour. See Errors, limits and polling.

What happens to feedback after it is sent

The game's crew reads it on the game's Feedback tab in the panel, newest first, filtered by category, status and days, and moves each piece through New, Seen, Planned, Done and Ignored. The assistant can summarise it. Nothing deletes feedback today.

Updated