Errors and Limits

HTTP status codes

Status	When	Body
`400`	`servers` missing or not an array	`{"error":"POST_2","message":"Invalid request format"}`
`400`	More than 1000 addresses in one request	`{"error":"POST_3","message":"Exceeded maximum server request limit (1000)"}`
`400`	Body is not valid JSON	`{"error":"POST_4","message":"Invalid JSON format"}`
`401`	An auth header is missing or the credentials do not resolve	`{"message":"API token is required"}`
`403`	The key's whitelist rejected the request origin	`{"message":"Request origin is blocked by API key whitelist settings"}`
`405`	`GET` on `/v1/post/fetch`	`{"error":"POST_1","message":"Method Not Allowed. Only POST requests are accepted."}`
`405`	Anything but `GET`/`OPTIONS` on `/v1/get/games`	`{"error":"GET_1","message":"Method Not Allowed. Only GET requests are accepted."}`
`429`	Rolling 24-hour quota exhausted	`{"message":"Daily quota exceeded for this API key","quota":1440,"used":1440}`
`500`	Database or Redis failure	`{"message":"Internal server error"}`

Codes are stable strings; the messages beside them are not a contract. Branch on error, and on the HTTP status, never on message text.

Code	Meaning
`GET_1`	Wrong method on `/v1/get/games`.
`POST_1`	Wrong method on `/v1/post/fetch`.
`POST_2`	`servers` is absent or is not an array.
`POST_3`	More than 1000 addresses across all groups.
`POST_4`	Malformed JSON body.

401 and 403 responses carry message only, with no error code.

Message	Cause
`API token is required`	`X-API-Token` header absent.
`API token Type is required`	`X-API-Token-Type` header absent.
`API token Type is invalid`	Type is not `FREE` or `PRO`.
`API token Email is required`	`X-API-Token-Email` header absent.
`Invalid/Stopped API Credentials. Check token email/type (FREE or PRO).`	Headers present but the key, email, package, key status or account status does not match.

Status	Retry
`400`, `401`, `403`, `405`	No. The request is wrong; retrying burns quota.
`429`	Only after backing off. Read `quota` and `used` first.
`500`	Yes, with exponential backoff and jitter.

1000 addresses per request, counted across every group in servers.
Request bodies are capped at 1 MB.
Addresses must match IPv4 ip:port. Hostnames, IPv6 and bare IPs are rejected.
POST /v1/post/fetch requires Content-Type: application/json.
Quota is per key over a rolling 24-hour window, 1440 by default, unlimited for PRO.

A batch never fails because some rows are bad. Invalid rows are separated out and the rest is served, with 200:

_meta.invalid_servers - rows that were rejected, with the reason implied by the shape (unknown game_id, empty group, or malformed address).
_meta.inserted_servers - game_id + address pairs newly registered by this request.
_meta.auto_inserted - the count of those pairs.

If your ingestion pipeline only checks the HTTP status, silent data loss is the default outcome. Treat these three fields as first-class output.