Troubleshooting

Each entry starts from what you see, explains the usual cause, and gives the fix. If you have an error code, the index at the bottom points to its entry.

First checks

Three things answer most questions:

1. The project’s Overview in the dashboard shows what’s set up: the setup checklist, today’s usage against the beta quotas, the managed wallet and its SOL balance, and the linking page URL.

2. rolink:GetProject() from a server script confirms the whole path at once: HTTP requests, the Secret, the API key and the project behind it.

   local project = rolink:GetProject()
   print(project.name, project.cluster, project.walletAddress, project.events, project.linkUrl)

   If this call fails, start with Game servers can’t reach Rolink.

3. The SDK’s error string names the problem. Every SDK error starts with [Rolink] <code>: <message>, errors that came back over HTTP end with (HTTP <status>), and Rolink.errorCode(err) extracts the code. Two codes come from the SDK itself: network_error (no answer at all) and http_<status> (an answer that wasn’t from the Rolink API).

Game servers can’t reach Rolink

HTTP requests are not enabled

Symptom. Every call fails with [Rolink] network_error: followed by Roblox’s message that HTTP requests are not enabled.

Cause. The experience doesn’t allow HttpService requests.

Fix. In Studio, open File → Experience Settings → Security, turn on Allow HTTP Requests, and save. The setting belongs to the experience, so it applies to live servers and Studio alike.

The Secret doesn’t work

Symptom. HttpService:GetSecret("rolink_api_key") raises an error, or calls fail with network_error and a message about the secret or its domain.

Cause. The secret doesn’t exist in this environment, or its domain doesn’t match the Rolink API’s host. Live servers read Secrets from your experience’s settings on the Creator Hub; Studio reads them from Local Secrets.

Fix. Check the secret’s name (rolink_api_key) and set its domain to api.rolink.tech. For Studio, add the same secret under File → Experience Settings → Security → Local Secrets. See Set up Roblox.

unauthorized (401)

Symptom. [Rolink] unauthorized: Missing or invalid x-api-key (HTTP 401).

Cause. The key the game sends isn’t an active key of any project. Common reasons:

• the key was revoked, or its project was deleted,
• the Secret’s value was cut short or picked up extra characters when pasted (a key is rlk_live_ followed by 43 characters),
• Studio’s Local Secret differs from the live one.

Fix. Under API keys in the dashboard, check that the key’s first characters match an active key. If in doubt, create a new key, paste it into the Secret again, and revoke the old one.

network_error

Symptom. [Rolink] network_error: <Roblox's message> after a couple of seconds.

Cause. No HTTP answer came back after 3 attempts: HTTP requests are disabled, the Secret’s domain is wrong, apiUrl is set to something unreachable, or the server hit HttpService’s own per-server limit (500 requests per minute).

Fix. Check the two entries above. Leave apiUrl unset so the SDK uses the default API URL. If your servers make many calls, see Read on-chain data for caching and batching.

http_502, http_504 and other http_ codes

Symptom. [Rolink] http_502: Bad Gateway (HTTP 502).

Cause. Something between your server and the Rolink API answered instead of the API, usually during a brief outage. The SDK has already retried 5xx answers twice.

Fix. Retry later. Transaction calls are safe to retry with the same idempotency key. If it lasts, check that apiUrl is unset, then contact Rolink support.

Quotas

rate_limited (429)

Cause. The project made more than 600 requests in the current minute, across all its servers.

Fix. The SDK retries this one after 0.5 and 1.5 seconds. If it keeps happening, cache more: GetWallet already caches, use GetWallets for many players at once, and avoid reading balances on a timer. See Read on-chain data.

daily_quota_exceeded (429)

Cause. The project used its 100,000 requests for the current UTC day. The SDK doesn’t retry it.

Fix. Requests work again after 00:00 UTC. Look at the usage chart on the Overview page to find what’s calling so often. See Limits and quotas.

daily_tx_quota_exceeded (429)

Cause. The project already has 1,000 transactions in the last 24 hours (failed ones don’t count). The SDK doesn’t retry it.

Fix. Queue the payment and retry later with the same key. If your game needs more during the beta, contact Rolink support.

The dashboard

The dashboard shows a refused action as a message on the page, next to the form or as an error page, not as a code. The codes in the headings below are for reference.

Dashboard sign-in fails

Cause. The dashboard signs you in with a Solana wallet, and its sign-in page says what went wrong:

Message	Cause
Request cancelled in your wallet.	You declined the connection or the message in your wallet.
This sign-in request expired. Try again. (challenge_expired)	More than 10 minutes passed between choosing the wallet and signing, or the browser blocks cookies.
The signature does not match this wallet (invalid_signature)	The wallet signed with another account than the one it connected, for example after you switched accounts mid-way.
Cross-origin request refused (bad_origin)	The page was opened through a proxy, a translation service or an embedded view.

Fix. Allow cookies for the Rolink API’s site, open the dashboard directly, then choose your wallet again and approve the message within 10 minutes. A dashboard session lasts 12 hours, then you sign in again.

No wallet on the sign-in page

Symptom. The dashboard’s sign-in page says “No Solana wallet found in this browser.” instead of listing your wallet.

Cause. The page found no wallet that can sign messages: none is installed, the extension is disabled or not allowed in private windows, or JavaScript is off, in which case the page also says “Signing in needs JavaScript.” It lists Wallet Standard wallets that support solana:signMessage, or an older injected provider with signMessage.

Fix. Install a Solana wallet such as Phantom, Solflare or Backpack, allow it on this site, and reload the page. The wallet needs no funds. On a phone, open the dashboard in your wallet app’s built-in browser.

project_limit_reached (403)

Cause. You already have 5 projects, the beta’s limit per developer.

Fix. Delete a project you no longer use, or reuse an existing one. Deleted projects don’t count.

key_limit_reached (403)

Cause. The project already has 10 active API keys.

Fix. Revoke a key you no longer use, then create the new one.

key_not_found (404)

Cause. You tried to revoke a key that is already revoked, or that belongs to another project.

Fix. Reload the API keys page. Nothing else to do.

project_not_found (404)

Cause. The project doesn’t exist, was deleted, or belongs to another developer account. On a linking page, the slug in the URL matches no project.

Fix. Check that you’re signed in with the wallet that created the project: each wallet is a separate account. For a linking page, copy the URL again from the Overview page or from GetProject().linkUrl.

invalid_settings (400)

Cause. A value you saved doesn’t pass validation. The form shows “Not saved.” with a message that names each field by its label and the problem, such as Per recipient wallet: Too big: expected number to be <=10000 or limit for <mint>: "0.5" has more than 0 decimals. The common ones:

Message	Fix
Name: at least 2 characters / Name: at most 48 characters	Project names are 2 to 48 characters.
Universe ID: digits only	Use the experience’s universe ID, a number. Not the place ID, not a URL.
Client ID: digits only	Paste your Roblox OAuth app’s client ID from Creator Dashboard: up to 32 digits.
Topic: letters, digits, - and _ only	Topics are 1 to 80 letters, digits, - and _.
Allowed mints (<value>): Invalid key in record	A mint field doesn’t hold a valid Solana address. Check it for typos.
<mint>: not a token mint on devnet (or mainnet)	The address isn’t a token mint on the project’s cluster. A devnet mint can’t be used in a mainnet project.
... has more than N decimals	Use no more decimals than the asset allows: 9 for SOL, the mint’s own for tokens.
hourly budget for <asset>: not an allowed mint	Add the mint under Allowed mints first, or set the budget for SOL.
Allowed mints: at most 20 mints	A policy allows up to 20 mints.
Watched addresses: at most 10 watched addresses	Remove a watch before adding another.
Name: lowercase letters, digits, - and _ (max 32)	Watch names start with a lowercase letter or digit.
Watched addresses: watch names must be unique	Pick another name.
Address: must be a Solana address	Check the watched address for typos.

When a form with a secret is refused, the Open Cloud key or client secret you typed isn’t kept. Paste it again.

Creating the wallet fails

Cause. The Managed wallet card says which:

• “Managed wallets aren’t set up on this server yet, so transactions are off.” (wallets_unavailable, 503): managed wallets aren’t turned on for the hosted API yet. Nothing is wrong with your project.
• “The wallet provider didn’t respond. Try again in a moment.” (502): the wallet provider couldn’t create the wallet. Nothing was created.

Fix. For wallets_unavailable, try again later. Linking, reads, live events and the rest of the dashboard work meanwhile, and transaction calls answer wallet_not_configured until the wallet exists. Otherwise, try again in a minute. If it keeps failing, contact Rolink support.

The test event fails

From Settings, the dashboard can send a test ping message through Open Cloud. It shows Roblox’s answer:

Answer	Fix
Add your universe ID and Open Cloud API key first.	Fill in both under Settings.
HTTP 401 or HTTP 403	The Open Cloud key is wrong, expired, restricted to other IP addresses, or lacks universe-messaging-service:publish on this experience. Fix it in Creator Hub → Open Cloud → API Keys, then paste it again.
HTTP 404	The universe ID is wrong. Use the experience’s universe ID, not a place ID.
HTTP 0	Roblox couldn’t be reached. Try again.

A successful test means Roblox accepted the message. The SDK ignores ping messages, so no signal fires in your game. See Events.

The linking page

“No game uses this link.”

Cause. The slug in the linking page URL matches no project, or the project was deleted.

Fix. Copy the URL again from the Overview page or from GetProject().linkUrl. Renaming a project doesn’t change its URL.

“This game hasn’t set up Roblox sign-in yet.”

Cause. The project has no Roblox OAuth app saved: its client ID or client secret is missing. Until both are saved, the page disables Continue with Roblox, and a sign-in attempt comes back with ?error=oauth_not_configured.

Fix. Create your game’s OAuth app in Creator Dashboard, then paste its client ID and client secret under the project’s Settings → Roblox sign-in, and save. The card shows on once both are saved. See Set up Roblox sign-in.

Roblox shows an error instead of its consent screen

Symptom. After Continue with Roblox, Roblox shows an error instead of asking the player to allow your app, and the player never gets back to your linking page.

Cause. Usually a redirect URL mismatch. Rolink always sends https://api.rolink.tech/auth/roblox/callback as the redirect URL, and Roblox only accepts one registered on the app. Yours is missing or differs: another host, http instead of https, a trailing slash or a typo. A mistyped client ID causes a similar error.

Fix. In Creator Dashboard, set the app’s redirect URL to exactly https://api.rolink.tech/auth/roblox/callback. Copy it from Settings → Roblox sign-in, and check the client ID saved there.

Only some players can sign in

Symptom. You and a few testers can sign in with Roblox on your linking page, but other players can’t.

Cause. Until Roblox reviews your OAuth app, it works for up to 10 users.

Fix. Get the app reviewed by Roblox: submit it for review in Creator Dashboard. Plan for this before you send players to your linking page.

Sign-in errors

When Sign in with Roblox fails, the player comes back to your linking page with ?error=<code> in the address, and the page shows a message:

Message	error	Cause	Fix
Roblox sign-in was cancelled.	roblox_denied	Roblox sent the player back with an error, usually because they declined on the consent screen.	Nothing to fix. The player can start again. If every player gets it, check that your app allows the openid and profile scopes.
Sign-in expired. Please try again.	oauth_state_mismatch	More than 10 minutes passed, the player finished in another browser (some in-app browsers hand off to the system browser), the callback was opened twice, or the browser blocks cookies.	Start again from the linking page, in one browser, with cookies allowed.
Roblox sign-in failed. Please try again.	oauth_token_failed	Roblox refused to exchange the sign-in code: the client secret saved in Rolink doesn’t match your app’s, or Roblox failed briefly.	Paste the app’s client secret again under Settings → Roblox sign-in, and save. If it’s right, try again later.
Couldn’t read your Roblox profile. Please try again.	oauth_userinfo_failed	Roblox refused the profile request.	Try again. If it lasts, contact Rolink support.
This game hasn’t set up Roblox sign-in yet.	oauth_not_configured	The project has no Roblox OAuth app saved.	Save the client ID and secret under Settings → Roblox sign-in. See above.

When the sign-in cookie is missing, Rolink can’t tell which game the player came from, and sends them to the Rolink dashboard instead of your linking page. Ask them to open your linking page again and sign in from one browser.

Signed in, but the page asks to sign in again

Cause. The browser didn’t keep the session cookie (cookies blocked, a private window that was closed), the session ended (player sessions last one hour), or the player signed in on another game’s linking page since. A session only counts on the game it was opened for, and a browser keeps one at a time.

Fix. Allow cookies for the Rolink API’s site and sign in again.

“No Solana wallet found in this browser.”

Cause. The page found no wallet: none installed, the extension is disabled or not allowed in private windows, the player is on a phone browser with no wallet injected, or the wallet doesn’t support message signing (the page needs solana:signMessage, or a legacy provider with signMessage).

Fix. Install a Solana wallet (Phantom, Solflare or Backpack, for example) and reload. On a phone, open the linking page inside the wallet app’s built-in browser.

“Cross-origin request refused” (bad_origin)

Cause. The request’s Origin header isn’t the Rolink API’s origin. This happens when the page is shown through a translation service, a proxy or an embedded view that rewrites or drops the header.

Fix. Open the linking page directly, at the URL from GetProject().linkUrl.

“This request expired. Try again.” (challenge_expired)

Cause. The player took more than 10 minutes to sign, the same challenge was submitted twice (each nonce is used once), or they signed in as another account in between.

Fix. Choose the wallet again. The page requests a fresh challenge every time.

“The signature does not match this wallet” (invalid_signature)

Cause. The wallet signed with a different account than the one it connected (the player switched accounts in the wallet mid-flow), or a wallet returned an unexpected signature format. Some hardware wallet setups can’t sign plain messages.

Fix. Select the intended account in the wallet, then choose the wallet again on the page. Try a software wallet if a hardware wallet keeps failing.

“Sign in with Roblox first” (not_signed_in)

Cause. The page has no valid session for this game: the session cookie is missing, expired (after one hour) while the page was open, or was opened on another game’s linking page. A session only counts on the game it was opened for.

Fix. Reload the page and sign in again.

A player linked, but the game says no wallet

Cause. The player linked on another game’s page (links are per project), or a “no wallet” answer is still cached in the SDK and live events are off.

Fix. Check that the link URL you show players is your project’s, from GetProject().linkUrl. Check under Players in the dashboard whether the link exists. Without live events, the SDK sees the new link once its cache entry expires (walletCacheSeconds, 60 by default).

Reads

invalid_mint (400)

Cause. The mint doesn’t exist on the project’s cluster, or the address isn’t a token mint. The usual culprit is a devnet mint used in a mainnet project, or the reverse.

Fix. Check the mint on an explorer for the project’s cluster (GetProject().cluster).

invalid_address, invalid_user_id, invalid_signature (400)

Cause. An input isn’t well formed: an address that isn’t a base58 Solana address, a user ID that isn’t a positive integer, or a string passed to GetSignatureStatus that isn’t a transaction signature.

Fix. Validate inputs before calling, especially anything that came from a player.

invalid_request or invalid_json (400)

Cause. A request body doesn’t match the route: for example more than 200 user IDs in one bulk lookup, an amount that isn’t a plain decimal string, or an idempotency key longer than 128 characters. The message names the field.

Fix. Fix the call. The SDK always sends valid JSON, so invalid_json only comes from your own HTTP client.

internal (500)

Cause. Something unexpected failed inside Rolink, most often the Solana RPC being briefly unavailable during a read.

Fix. The SDK retries it. If it lasts, contact Rolink support with the time and the call you made.

A balance looks out of date

Cause. Balance, token and asset reads are cached for about 10 seconds, and balances are read at confirmed commitment.

Fix. Expected behavior. Read again a little later.

Events don’t arrive

Work through these in order:

1. Are events configured? GetProject().events must be true. If not, add the universe ID and an Open Cloud API key under Settings.
2. Does Roblox accept the messages? Send a test event from Settings. See The test event fails.
3. Is it the right universe? The universe ID is the experience’s, not a place ID. With a key that covers several experiences, a wrong ID sends events to another one.
4. Do the topics match? The event topic in the dashboard must equal topic in Rolink.new. Both default to rolink.
5. Did the server subscribe? Look for [Rolink] could not subscribe to topic in the server’s output. After 5 failed attempts it stops trying. Also check that nothing passes subscribe = false or calls :Destroy().
6. Are you listening on the right client? Connect handlers to the same shared client your other scripts use, and connect them when the script starts.

Even when everything is right, MessagingService is best effort, so an occasional event can still be lost. Read from Rolink when the answer matters. See Live events.

Transactions

wallet_not_configured (409)

Cause. The project has no managed wallet yet.

Fix. Select Create wallet on the project’s Overview page, then fund it. See Send transactions.

mint_not_allowed, amount_over_limit, sol_transfers_disabled (403)

Cause. The request is outside your policy: the mint isn’t under Allowed mints, the amount is above its per-transaction cap (or above Max SOL per transfer), or SOL transfers are off.

Fix. Change the request, or the policy under Transactions if the request is legitimate. Policy changes take effect within about 30 seconds. The key wasn’t reserved, so you can retry with the same one.

invalid_amount (400)

Cause. The amount is zero, or has more decimals than the asset allows (9 for SOL). A string that isn’t a plain decimal at all, such as "-1", "1e3" or "1,5", is refused earlier as invalid_request.

Fix. Pass a positive decimal string within the asset’s decimals, such as "1.5".

wallet_not_linked (404)

Cause. You sent to a UserId that has no wallet linked to this project.

Fix. Ask the player to link one on your linking page, then retry with the same key. Nothing was reserved.

recipient_rate_limited or player_rate_limited (429)

Cause. That wallet, or that player across all their wallets, already received the hourly maximum set under Per recipient wallet or Per player (20 by default) in the last 60 minutes. Failed attempts don’t count. The SDK doesn’t retry these.

Fix. Queue the payment and retry later with the same key. If legitimate traffic hits the limit, pay less often (one reward per session instead of one per action), or raise the limit.

hourly_budget_exceeded (429)

Cause. The total sent for that asset in the last 60 minutes, plus this request, would exceed its hourly budget.

Fix. Treat it as an alarm first: look at the project’s recent transactions in the dashboard. If the traffic is legitimate, retry later with the same key, or raise the budget.

idempotency_conflict (409)

Cause. The key was already used in this project for a different request: another method, recipient, mint or amount. "1" and "1.0" count as different, and so do a UserId and that player’s address.

Fix. Make keys specific to one payment. If the same key really produced a different amount, the conflict caught a bug: find out why before changing anything.

wallet_unavailable (502)

Cause. The managed wallet couldn’t sign the transaction. Nothing was sent, and the attempt is recorded as failed.

Fix. The SDK retries automatically. Otherwise retry later with the same key. If it lasts, contact Rolink support.

rpc_error (502)

Cause. The Solana RPC couldn’t be reached to build the transaction. Nothing was sent, and the attempt is recorded as failed.

Fix. The SDK retries automatically. Otherwise retry later with the same key.

invalid_limit_config (422)

Cause. An amount in the stored policy can’t be represented with the asset’s decimals. The dashboard checks this when you save, so it’s rare.

Fix. Open Transactions in the dashboard and save the policy again. The dashboard points out the value to fix.

The result is failed

Cause. The error field says which stage failed:

• Solana error #-32002; Decode this error by running ... (the hosted API reports simulation errors in this coded form, and running the quoted npx @solana/errors decode command turns it back into text) means the network simulated the transaction and rejected it, so it was never sent. The usual causes: the managed wallet has no SOL for fees, doesn’t hold enough of the token for TransferToken, isn’t the mint authority for MintToken, or a SOL transfer to an empty address is below the rent-exempt minimum (about 0.00089 SOL).
• A JSON error from the chain, such as {"InstructionError":[1,{"Custom":1}]}, means the transaction landed and failed on-chain. The network fee was paid, but nothing reached the recipient.
• Transaction expired before it was confirmed means it never landed, and Rolink proved it no longer can.
• Could not build the transaction: ... means the RPC couldn’t be reached. The request also answered rpc_error.
• Turnkey refused to sign: ... or another message about the wallet provider means the managed wallet couldn’t sign. The request also answered wallet_unavailable.
• Abandoned before sending means the request was interrupted between reserving the key and sending. Nothing was sent.

Fix. Check the managed wallet’s SOL and token balances on an explorer for the project’s cluster, fix the cause, then retry with the same key. A failed attempt delivered nothing, so retrying is safe.

“submitted” never becomes final

Cause. The transaction was sent but hasn’t confirmed, and Rolink can’t yet prove it expired. Possible reasons:

• Congestion. Rolink doesn’t add a priority fee, so under heavy mainnet load a transaction can take longer or not land. If it doesn’t land, it’s reported failed (expired) a minute or two later, once that’s provable.
• A lagging RPC. Expiry is only declared on evidence from a node that has caught up with the finalized chain.
• No live events. Without Open Cloud, TransactionUpdated never fires, even though the status changed.

Fix. Call rolink:GetTransaction(key): it returns the current status and nudges Rolink to check. Look up the signature on an explorer for the project’s cluster. Don’t send the payment again with a new key while one is submitted.

Error code index

Code	HTTP	Where	Entry
unauthorized	401	Game API	unauthorized
rate_limited	429	Game API	rate_limited
daily_quota_exceeded	429	Game API	daily_quota_exceeded
invalid_request / invalid_json	400	Any	Malformed body
invalid_user_id / invalid_address	400	Game API, linking, dashboard sign-in	Malformed input
invalid_signature	400	Game API, linking, dashboard sign-in	Reads, linking, dashboard
invalid_mint	400	Game API	invalid_mint
not_found	404	Any	Unknown route, or GetTransaction for a key the project never accepted.
internal	500	Any	internal
wallet_not_configured	409	Transactions	wallet_not_configured
invalid_amount	400	Transactions	invalid_amount
wallet_not_linked	404	Transactions	wallet_not_linked
mint_not_allowed / amount_over_limit / sol_transfers_disabled	403	Transactions	Policy refusals
recipient_rate_limited / player_rate_limited	429	Transactions	Hourly limits
hourly_budget_exceeded	429	Transactions	Budgets
daily_tx_quota_exceeded	429	Transactions	daily_tx_quota_exceeded
idempotency_conflict	409	Transactions	idempotency_conflict
invalid_limit_config	422	Transactions	invalid_limit_config
wallet_unavailable	502	Transactions	wallet_unavailable
rpc_error	502	Transactions	rpc_error
project_not_found	404	Dashboard, linking	project_not_found
project_limit_reached	403	Dashboard	project_limit_reached
key_limit_reached	403	Dashboard	key_limit_reached
key_not_found	404	Dashboard	key_not_found
invalid_settings	400	Dashboard	invalid_settings
wallets_unavailable	503	Dashboard	Creating the wallet fails
not_signed_in	401	Linking page	not_signed_in
bad_origin	403	Linking page, dashboard	bad_origin, dashboard sign-in
challenge_expired	400	Linking page, dashboard sign-in	challenge_expired, dashboard sign-in
oauth_not_configured	redirect	Linking page	Roblox sign-in isn’t set up
roblox_denied / oauth_state_mismatch / oauth_token_failed / oauth_userinfo_failed	redirect	Linking page	Sign-in errors
network_error	n/a	SDK	network_error
http_<status>	any	SDK	Proxy errors

The Error codes reference has the same list in reference form.

Still stuck?

Tip

A support address is on its way. When you write, give your project's name, the exact error string, the time it happened and what you expected. Leave out API keys and Open Cloud keys: support never needs them.