Getting started

Errors

The API uses conventional HTTP status codes and always returns a consistent JSON error shape.

Error shape

Every error response has an error code (stable, safe to switch on) and a message (human-readable, may change):

json

{
  "error": "invalid_replay",
  "message": "The uploaded file could not be parsed as an Unreal replay."
}

Status codes

Status	error	Meaning
`400`	`invalid_replay`	The file is corrupt or of an unsupported replay format.
`400`	`invalid_request`	The request body or parameters failed validation.
`401`	`unauthorized`	The API key is missing or invalid.
`403`	`forbidden`	The key is not allowed to perform this action — e.g. a legacy key (or a key bound to another guild) calling guild endpoints.
`403`	`premium_required`	The guild is not on the Premium or Pro plan required for the Guild API.
`404`	`not_found`	The requested resource does not exist (unknown guild, session, team, link, …).
`409`	`conflict`	The request conflicts with current state — e.g. a member or Epic account that is already linked, or a team already signed up.
`413`	`file_too_large`	The upload exceeds the `35 MB` limit.
`415`	`unsupported_file`	The upload is not a .replay file (fails the magic-byte check).
`422`	`parse_timeout`	Parsing took too long and was aborted.
`429`	`rate_limited`	You exceeded your rate limit. Retry after the given delay.
`500`	`internal_error`	An unexpected server error occurred. Safe to retry.
`503`	`busy`	The service is temporarily overloaded. Retry with backoff.

Handling errors

Branch on the error code rather than the message text. Codes are stable across releases; messages are for humans and may be reworded. For 429, honor the Retry-After header; for 500, a retry with backoff is safe.