Skip to content

Error codes

When something goes wrong, otomo and the SDK report a short, fixed code: a word such as network or not_in_party. You'll find it in OtomoError.Code in your C# code, in the errorCode of the PatchFinished signal, and in the SDK's log lines, like this:

GET /api/player/session/party -> 404 not_in_party request_id=01a0ecdd-ed6b-7df5-8025-9701e4d593d0

That line says: the request GET /api/player/session/party got status 404 with code not_in_party, and its ID in the server logs is 01a0ecdd-…. Status codes are explained in HTTP and APIs.

Reporting a problem

Always include the request_id. With it, whoever checks the server finds your exact request in the admin website's Logs page in seconds. Without it, they're guessing.

From the SDK itself (status 0)

These happen on the player's computer, before or without a server answer. Status is 0.

Code Meaning What to do
network Couldn't connect to otomo: no internet, wrong Base Url, or the server is down Check the internet connection and the Base Url setting. The game carries on offline with its last content.
timeout The server took too long to answer Usually temporary; try again. If it keeps happening, the server may be overloaded.
bad_response The server answered with something the SDK couldn't read Usually a mismatch between SDK and server versions. Report it with the request_id.
bad_manifest The content list from Patch is malformed or unsafe Report it; the SDK keeps the last good content.
missing_blob A file the release needs wasn't on disk when the SDK went to load it Usually the download was interrupted or the files were deleted mid-run. Start the game again; it downloads what's missing.
size_mismatch A download came out bigger than the release says the file is Try again. If it repeats, report it with the release number.
pack_mount_failed Godot couldn't load a downloaded pack The .pck may be for another Godot version, or damaged. Rebuild and re-upload it.
download_declined The player said no to the download Not an error: the game carries on with its old content.
unknown The server answered with an error but without otomo's usual error details Check the Status; report it with the request_id.
sign_in_cancelled The player closed or declined the browser sign-in for Google or another provider Not an error to report: offer the sign-in choices again.
state_mismatch, sign_in_failed The browser came back with a sign-in this game did not start, or the provider refused it Ask the player to try again. Nothing was sent to the server.
browser_unavailable The SDK could not open the system browser Set AuthClient.BrowserLauncher (in Godot, to one that calls OS.ShellOpen).

Logins (any request)

Status Code Meaning What to do
401 missing_token The request had no login token The SDK adds tokens itself. If you send requests by hand, include Authorization: Bearer ….
401 expired The access token has expired The SDK renews it and retries automatically.
401 invalid_token, invalid_signature, iss_mismatch, aud_mismatch The token isn't valid for otomo The SDK logs in again. If it persists, AuthenticationLost fires.
403 insufficient_role A staff account lacks the role for this action Ask an admin for a higher role (Use the admin website).
400 invalid_device_id (at /auth/anonymous) The saved device ID is not the 43 characters the SDK makes, usually because someone edited the file by hand Delete otomo/device_id in the user data folder. This creates a new account.
429 rate_limit_exceeded Too many requests too quickly Wait a moment. If your code causes this, look for a loop sending requests every frame.

Steam, Google and other provider sign-in, and linked accounts

Answered by /auth/steam, /auth/google, /auth/oauth/<name> and /auth/identities (design/21-sign-in-and-linking.md §4). The rows below say Steam where the cause differs; for Google and the other providers invalid_credential means the authorization code was used, expired or forged, or the redirect URI or PKCE verifier did not match. How to set them up: Sign in with Steam, Google and others.

Status Code Meaning What to do
401 (sign-in) / 422 (link) invalid_credential Steam did not accept the ticket: it was used before, expired, made for another game, or made with another identity string Ask Steamworks for a new ticket with GetAuthTicketForWebApi and the identity your server uses, then try again. A link answers 422 so the player stays signed in.
403 provider_banned The Steam account is banned from this game by its publisher Show the message; trying again will not help.
409 identity_taken That Steam account is already linked to another otomo account Sign in with Steam instead, or unlink it from the other account first. Accounts are never merged.
409 method_already_linked This account already has a different Steam account linked Unlink the old one first.
409 last_identity Removing this sign-in method would leave the account with no way to sign in Link another method before removing this one.
400 invalid_redirect_uri Google or another OAuth sign-in or link used a redirect URI the server does not accept (not an allow-listed URI, not http://127.0.0.1:<port>/, or localhost) A bug in the calling code: use Pkce.LoopbackRedirectUri or the exact allow-listed URI.
404 not_found (at /auth/oauth/<name>) No provider of that name is configured Check the name against the operator's AUTH_OAUTH_PROVIDERS.
400 invalid_method The unlink named something that is not a sign-in method name (2 to 16 lower-case letters and digits) A bug in the calling code.
429 quota_exceeded A Steam sign-in would create a new account and this address has made too many today Wait for Retry-After, or raise AUTH_CREATE_QUOTA_PER_IP_HOUR for an event. Players who already have an account are never refused.
503 provider_not_configured This server has no Steam app id or publisher key set Hide the Steam button; the operator sets AUTH_STEAM_APP_ID and the publisher key (deploy/.env.example says how).
503 provider_unavailable Steam did not answer, or refused this server's own key Try again after Retry-After. If it lasts, the operator checks the key and Steam's status.

Content

Status Code Meaning What to do
409 release_outdated The game's content release isn't the current one (your team published or rolled back while it was running) Run patching again, then retry. The SDK will do this automatically in a future version.
400 invalid_release The release number the game sent isn't a valid number A bug in the calling code.
426 client_outdated This build of the game is older than the minimum the live release allows, or it sent no X-Otomo-Client-Version while the gate is enforced. Answered by the gateway, login, refresh and every Session player route Show UpdateRequired.Message and offer UpdateRequired.Target (a download page, the store, or Steam). The SDK sends the headers itself; error.details carries the release's whole client_update block.

Replays (Patch)

The upload and report routes of Record and share replays. The SDK turns these into RecordingFailure values on UploadResult.

Status Code Meaning What to do
403 not_host Only the host of a peer-hosted match uploads its replay Do not offer the upload to peers.
403 players_not_in_match A player named in the upload was not on the match roster Name only players of the match.
403 upload_window_closed The match ended too long ago Upload at the end of the match, and retry soon after a failure.
404 no_match Patch does not know that match Use the match id from the match record.
409 not_p2p The match was not placed on a peer-hosted room Dedicated matches have no player host.
409 recording_conflict This match already holds a different recording, or a retry differs from the stored one in bytes, format, meta, tags or players Keep one replay per match and retry it unchanged.
403 recording_removed Staff removed this recording; it cannot be uploaded again Do not retry.
413 recording_too_large Over the upload cap (8 MiB by default) Record less, or quantise harder.
400 digest_mismatch, size_mismatch The bytes are not what the form declared The file changed while uploading; try again.
400 unsupported_kind This instance does not accept that replay format Use the format the instance allows.
429 rate_limited Too many upload attempts too fast Wait Retry-After; the SDK retries short waits itself.
429 quota_exceeded The player's daily replay allowance is used up Try again after Retry-After (the next UTC midnight).
429 report_limit Too many reports today Try again later.
503 host_check_unavailable The match could not be verified just now Retry; the SDK does within its attempts. Keep the file.
503 storage_full The recording store is full Retry much later; tell the operator.
503 busy Too many uploads in flight Retry shortly.

Profiles, friends and parties (Session)

Status Code Meaning
404 not_in_party The player isn't in a party. Normal before creating one.
409 already_in_party The player must leave their current party first
403 not_leader Only the party leader can do this
409 revision_mismatch Someone changed the party first. Fetch it again and retry (Parties and matches).
400 revision_required The leader's request didn't include the party's revision number
409 party_locked The party is launching, queued for matchmaking or in a match; only leaving is allowed, and while queued not even that
409 party_full The party has reached its maximum size
409 not_ready Launch refused: not every member is ready
400 / 409 invalid_settings A lobby setting or value isn't allowed by session.rules
409 not_in_game Asked for a join ticket, but the party isn't in a match
409 match_ended The match is over; launch a new one
404 not_in_match The player isn't part of that match
503 maintenance The service is closed for a maintenance window; Retry-After and error.details say when to try again. Answered by the gateway, Auth and Session
503 allocator_unavailable Session couldn't reach the Allocator; try again shortly
503 launch_unavailable Launching isn't switched on for this server
409 name_unavailable That display name is taken or not allowed
400 invalid_display_name The name breaks the naming rules. On a rename, error.details.rule says which: required, encoding, length, characters or reserved, with min_length and max_length
429 rate_limit_exceeded (rename) Renamed too recently. Retry-After and error.details.retry_after_seconds say how long is left, retry_at when. The SDK's TryRenameAsync reports it as Cooldown
409 already_friends / friend_limit Already friends / the friends list is full
403 blocked One player has blocked the other
404 player_not_found, profile_not_found, not_friends, invite_not_found, request_not_found The player, profile, friendship, invite or friend request doesn't exist
410 invite_expired The party invite is too old

Joining a match (Gameplay Proxy)

The proxy speaks UDP, not HTTP, so these arrive as a reason number, and the launch code turns them into a message.

Reason Message Meaning What to do
1 invalid The ticket is damaged, forged, or the proxy is full Join again
2 expired The ticket is older than 60 seconds Join again; a fresh ticket is fetched
3 already used This ticket was already used from another address Join again
4 unknown server The game server in the ticket isn't registered Join again; if it repeats, check the game servers (Run a new game server build)

Anywhere

Status Code Meaning
400 validation_failed, invalid_body, invalid_request Something in the request is missing or malformed. message says what.
404 not_found No such route: check the path
405 method_not_allowed The path exists, but not with that method (GET instead of POST, for example)
413 body_too_large The request body is too big
500 internal_error A bug on the server. Report it with the request_id.
502 upstream_error The gateway couldn't reach the service behind it
503 not_ready The service is starting up or has lost its database; try again in a moment