Errors and status codes#

Status codes#

Status	Meaning
`200`	Success
`201`	Created
`400`	Invalid input
`401`	Auth or permission issue (invalid or missing API key)
`403`	Forbidden (insufficient permissions, inactive project, …)
`404`	Not found
`405`	Method not allowed
`429`	Rate limited — back off and retry
`500`	Server error

Error responses#

Error responses carry a machine-readable error field:

{ "error": "invalid_api_key" }

`error`	Status	Meaning
`missing_api_key`	`401`	No `X-Api-Key` header and no `Authorization: ApiKey …`
`invalid_api_key`	`401`	No key matches, the key was revoked, or your IP is not allowed
`expired_api_key`	`401`	The key was real, but its regeneration grace period has ended
`insufficient_scope`	`403`	Valid key, wrong kind for this route
`inactive_client`	`403`	The project is inactive on Gamearly
`rate_limited`	`429`	Back off and retry

insufficient_scope names both sides, so you can see at a glance which key you used:

{
  "error": "insufficient_scope",
  "required": ["quests:write"],
  "granted": ["events:write", "link:read", "link:write", "project:read", "users:read"],
  "key_kind": "public"
}

key_kind: "public" on a route that needs a private scope means the call is coming from your game rather than your server. See Authentication.

Ingest is different#

Partial success on batches

/events/track and /events/import do not fail the whole batch when individual events are bad. They return 200 with the batch partitioned into accepted, duplicated, throttled and rejected. See Sending events.