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:
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 |