Errors

Every gbandit API answers a failure with an RFC 9457 Problem Details body, Content-Type: application/problem+json. That holds for the platform API, the CLI endpoints, and the platform's own answers on your game's address (/api while the backend is asleep, a game that doesn't exist, ...).

{
  "type": "https://docs.gbandit.com/errors#nothing-to-promote",
  "title": "Nothing to promote",
  "status": 409,
  "detail": "There is nothing in dev to promote yet. Run `gbandit deploy` first, then promote.",
  "request_id": "0b6f1c9e-…",
  "retryable": false
}

Member	Meaning
type	What kind of failure this is. Branch on this, never on title or detail. about:blank means nothing beyond the status code.
title	Short, fixed summary of the type.
status	The HTTP status, repeated.
detail	What happened this time and what to do about it. Written to be shown to a person.
request_id	The id the platform logged the request under. Quote it when you ask for help.
retryable	Whether sending the same request again can succeed.
issues	Field-level problems, each with path, message and docs_url.
diagnostics	Raw technical output, such as git's stderr. Useful for debugging, not for showing by default.

A type can add members of its own; they are listed under it below. Ignore members you don't know.

platform-error

5xx. Something broke on our side, not in your code or your request. The detail never says why; quote the request_id when you ask for help. Retry when retryable is true.

Deploying and promoting

nothing-to-promote

409. gbandit promote with nothing in dev to promote. Run gbandit deploy first.

cli-outdated

426. The gbandit CLI is older than the oldest version the platform supports. Run gbandit update.

config-missing

422. The uploaded source has no gbandit.jsonc at its root. See gbandit.jsonc.

invalid-config

422. gbandit.jsonc does not validate. issues lists every problem, each with the path in the file, a message, and a docs_url to the section that explains it.

google-account-required

403. A guest account tried to run a backend or a database, or to use the AI agent. Log in with Google (gbandit login); your projects come with you.

database-removal-requires-confirmation

409. The deploy or promotion would remove a provisioned database, which deletes its data. Repeat it with the confirmation; see Removing a database.

project-suspended

403. The project's creator has been suspended, so the project is neither served nor changed. The game's address answers with it too, and a browser gets a page saying the game is suspended. Questions go to abuse@gbandit.com.

Signing in

These come from auth.gbandit.com, including POST /api/token; see Authentication.

account-suspended

403. The platform has suspended this account. Signing in again can't help, so don't send the player to the login page. Questions go to abuse@gbandit.com.

session-expired

401. The player's session expired, and it belonged to an account they can sign back in to. Send them to sign in instead of carrying on as a new guest.

guest-limit-reached

429. The player's network already holds as many guest accounts as it may. Send them to sign in.

authorization-pending

400. gbandit login polls while the login waits in the browser, and gets one of these four answers until it is done. This one means nobody has approved it yet; poll again after the interval the start of the login gave.

access-denied

400. The person denied the login in the browser. Stop polling.

expired-token

400. The login expired before anyone approved it. Start a new one.

invalid-grant

400. The device code names no login, or the login was already completed. Start a new one.

Project data

no-database

409. The environment declares no database, so there is nothing to query. See Databases.

ai-spend-paused

402. The weekly AI budget is used up, so new messages are refused until the reset. Work that is already running may finish. usage carries the budget and reset_at.

Your game's address

These come from the platform, not from your backend, when a request to your game's domain can't reach it. A browser navigation gets a page instead.

game-not-found

404. No project has this name.

nothing-deployed

404. The project exists, but nothing has been deployed to this environment.

no-backend

404. The environment has no backend, so nothing answers /api.

game-starting

503. The backend was asleep and is starting. Retry after the number of seconds in Retry-After.

Linked repository

Git operations the agent's workspace runs against your linked repository.

divergent-history

409. The workspace and the remote both have commits the other doesn't. workspace and remote say how far ahead each side is and list its latest commits; remote_main_sha is the remote's main. Choose which side to keep.

git-auth-rejected

403. The Git host refused the deploy key. Check that the key is installed with write access, then try again.

git-host-unreachable

502. The Git host could not be reached. Check the remote URL and try again.

git-failed

500. Git failed for another reason, for example a protected branch. diagnostics holds git's output.

The agent

Messages to the agent that works on your Project.

conversation-not-found

404. The conversation doesn't exist. A conversation starts with its first message; start a new one.