From 5093cdff7960267c482786cb9bdcba59cc846bce Mon Sep 17 00:00:00 2001 From: tudor <7089284+tudddorrr@users.noreply.github.com> Date: Wed, 19 Aug 2026 02:18:10 +0100 Subject: [PATCH] add admin api common errors documentation --- content/docs/admin/common-errors.mdx | 69 ++++++++++++++++++++++++++++ content/docs/admin/dev-data.mdx | 32 +++++++++++++ content/docs/admin/meta.json | 2 +- content/docs/http/common-errors.mdx | 23 ++++++---- 4 files changed, 115 insertions(+), 11 deletions(-) create mode 100644 content/docs/admin/common-errors.mdx create mode 100644 content/docs/admin/dev-data.mdx diff --git a/content/docs/admin/common-errors.mdx b/content/docs/admin/common-errors.mdx new file mode 100644 index 0000000..39abe57 --- /dev/null +++ b/content/docs/admin/common-errors.mdx @@ -0,0 +1,69 @@ +--- +description: Debug common issues with Admin API requests. +title: Common errors +--- + +## Missing authentication + +`401 Unauthorized` + +The `Authorization` header is required, with its value set to `Bearer your-admin-api-key`. + +Admin API keys are prefixed with `ta_` and are created inside the [dashboard](https://dashboard.trytalo.com/api-keys). Unlike the gameplay [HTTP API](/docs/http/authentication), admin API keys are scoped to a single game rather than authenticating on behalf of a player. + +## Missing scopes + +```json +403 Forbidden + +{ "message": "Missing admin API key scope(s): [scopes]" } +``` + +This means your admin API key is missing the scopes required by the endpoint. You can update the scopes of an admin API key inside the dashboard. + +Generally, `GET` requests require `read` access and `POST/PUT/PATCH/DELETE` requests require `write` access. + +## Missing parameters + +`400 Bad Request` + +When omitting or providing an invalid parameter (e.g. a body param, query param or route param), you'll receive this error. Refer to the documentation for the endpoint to make sure your request is correct. + +The error object returns a key for every invalid/missing field, with an array of messages for each: + +```json +"errors": { + "internalName": ["internalName is required"], + "minValue": ["minValue must be less than maxValue"] +} +``` + +Each message corresponds to a failed validation rule on that field, so the response can include more than one error at a time. + +## Resource not found + +`404 Not Found` + +The requested resource doesn't exist for your game. This commonly happens when an ID in the route doesn't match an existing stat or leaderboard, for example: + +```json +{ "message": "Stat not found" } +``` + +```json +{ "message": "Leaderboard not found" } +``` + +## Rate-limiting + +`429 Too Many Requests` + +Receiving this status means you've hit Talo's rate limit. Rate limits use a fixed window (resets every minute), so you should aim to make less than 100 requests per minute. + +The `Retry-After` header will return how many seconds to wait before retrying - typically this will be set to '60' (the remaining seconds until the window resets). + +## Dev data + +Admin endpoints that read entities (e.g. listing leaderboard entries or listing stats) respect the `X-Talo-Include-Dev-Data` header. Set it to `1` to include development data, or leave it unset to only return live data. + +Learn more in the [dev data guide](/docs/admin/dev-data). diff --git a/content/docs/admin/dev-data.mdx b/content/docs/admin/dev-data.mdx new file mode 100644 index 0000000..1aa61d2 --- /dev/null +++ b/content/docs/admin/dev-data.mdx @@ -0,0 +1,32 @@ +--- +description: Separate development data from live data when using the Admin API. +title: Separating development data +--- +## Dev build headers + +When creating players through the [HTTP API](/docs/http/dev-data), you can optionally specify if the player belongs to a development build and therefore if they should be excluded from live data. + +By default, the Admin API only returns data associated with live players. To include development data in these reads, set the `X-Talo-Include-Dev-Data` header to `1`. + +Some endpoints behave differently depending on whether this header is set. For example, when fetching stat metrics, data from dev players will only be included if the header is set. + +## Resetting dev data + +Some entities like leaderboards and stats can be reset. This is controlled by the `mode` query parameter rather than the header. It accepts one of: + +- `all` - reset everything (the default) +- `live` - reset only live players +- `dev` - reset only dev players + +For example, to reset only dev player leaderboard entries: + +``` +DELETE /admin/v1/leaderboards/12345/entries?mode=dev +``` + +Or to reset only dev player stats: + +``` +DELETE /admin/v1/game-stats/67890/player-stats?mode=dev +``` + diff --git a/content/docs/admin/meta.json b/content/docs/admin/meta.json index 4de2c3a..510be69 100644 --- a/content/docs/admin/meta.json +++ b/content/docs/admin/meta.json @@ -1,5 +1,5 @@ { - "pages": ["authentication", "game-stat-api", "leaderboard-api"], + "pages": ["authentication", "common-errors", "dev-data", "game-stat-api", "leaderboard-api"], "title": "Admin API reference", "icon": "admin" } diff --git a/content/docs/http/common-errors.mdx b/content/docs/http/common-errors.mdx index aa2a9b2..6562773 100644 --- a/content/docs/http/common-errors.mdx +++ b/content/docs/http/common-errors.mdx @@ -11,11 +11,14 @@ The `Authorization` header is required, with its value set to `Bearer your-acces ## Missing scopes -`403 Forbidden - { message: 'Missing API key scope(s): [scopes]' }` +```json +403 Forbidden +{ "message": "Missing API key scope(s): [scopes]" } +``` This means your API key is missing scopes for the specified resource. You can update your API key inside the dashboard. -Generally, `GET` requests require `read` access, `POST/PUT/PATCH/DELETE` requests require `write` access. +Generally, `GET` requests require `read` access and `POST/PUT/PATCH/DELETE` requests require `write` access. ## Missing parameters @@ -23,11 +26,11 @@ Generally, `GET` requests require `read` access, `POST/PUT/PATCH/DELETE` request When omitting a required parameter (e.g. a query param, body param or header), you'll usually receive this error. Refer to the documentation for the API to make sure your request is correct. -The error object returned may be a single message, for example `{ message: Something went wrong }`, or an error object, which includes a key for every invalid/missing key: +The error object returned may be a single message, for example `{ "message": "Something went wrong" }`, or an error object, which includes a key for every invalid/missing key: -``` -errors: { - events: ['events is missing from the request body'] +```json +"errors": { + "events": ["events is missing from the request body"] } ``` @@ -43,14 +46,14 @@ The `Retry-After` header will return how many seconds to wait before retrying - ## Missing or invalid session -``` +```json 401 Authorized -{ message: 'The x-talo-session header is required for this player', errorCode: 'MISSING_SESSION' } +{ "message": "The x-talo-session header is required for this player", "errorCode": "MISSING_SESSION" } ``` -``` +```json 401 Authorized -{ message: 'The x-talo-session header is invalid', errorCode: 'INVALID_SESSION' } +{ "message": "The x-talo-session header is invalid", "errorCode": "INVALID_SESSION" } ``` When calling API endpoints on behalf of a player (i.e. using the `x-talo-player` or `x-talo-alias` header) that is using [player authentication](https://trytalo.com/players#authentication) you must also send a valid `x-talo-session` header.