REFERENCE
APIs and error codes
For calling the APIs yourself without a Skill. Leaderboards and cloud saves use separate tokens; never mix them.
| When | Endpoint | Key detail |
|---|---|---|
| Read settings | GET /api/v1/games/{gameId}/leaderboards | Enabled boards |
| Round start | POST /api/v1/leaderboards/{boardId}/runs | Player token + new request key |
| Final result | POST /api/v1/runs/{runId}/score | {"score":12800} |
| Standings | GET /api/v1/leaderboards/{boardId}/entries | limit and cursor pagination |
| My rank | GET /api/v1/leaderboards/{boardId}/me?around=2 | Personal result and neighbors |
| Action | Endpoint or method | Result or requirement |
|---|---|---|
| Initialize | AIWanna.saves.initialize(options) | Wait for restoration before play |
| Checkpoint | AIWanna.saves.save() | Complete state snapshot |
| Read cloud save | GET /api/v1/games/{gameId}/saves/main | save + revision |
| Write cloud save | PUT /api/v1/games/{gameId}/saves/main | baseRevision + Idempotency-Key |
| Status | Code | What to do |
|---|---|---|
| 400 | INVALID_INPUT / INVALID_CURSOR | Check the fields, or read again from the first page |
| 401 | SESSION_EXPIRED | Reconnect through the platform player |
| 403 | FORBIDDEN | No permission, wrong game or origin, or you are not the creator |
| 404 | NOT_FOUND / BOARD_UNAVAILABLE / RUN_NOT_FOUND | Check the IDs and that the board is enabled |
| 409 | ALREADY_SUBMITTED / BOARD_KEY_EXISTS | A settled run cannot change; board keys must be unique |
| 410 | RUN_EXPIRED | Past the two-hour limit for a run |
| 422 | INVALID_SCORE / BOARD_LIMIT | Score out of range or played too briefly; or already 10 boards |
| 429 | RATE_LIMITED | Wait for Retry-After (60 s) and try again |
| 503 | SERVICE_UNAVAILABLE | Retry later; the game keeps going |
| Status | Error | What to do |
|---|---|---|
| 401 | Token expired | Refresh the save token and retry the same request |
| 409 | Revision conflict | Both devices changed it: keep both and let the player choose |
| 409 | IDENTITY_CHANGED | The account changed: cancel, read again and confirm |
| 429 | Too many requests | Wait for Retry-After |
| — | Network failure | Not an empty save: queue it locally and never overwrite |
Full leaderboard API ↗Full cloud-save protocol ↗
Stuck? Send us the error and your prompt here.