Add admin API common errors documentation

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).

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
+```
+

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"
 }

content/docs/http/common-errors.mdx

@@ -11,23 +11,26 @@ 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
 
 `400 Bad 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.