Common Xtream API Errors and What They Mean
Xtream API errors appear in both the HTTP response and the JSON body. Their meaning varies by server — learn how to read both layers together.
Errors from an Xtream-compatible server typically appear in two places: the HTTP status code and the application-level data in the JSON response body. Neither alone tells the complete story — a server may return HTTP 200 alongside application-level error data, or an HTTP error code for a reason unrelated to credentials. Reading both layers together is the most reliable starting point.
Why Xtream Errors Are Not Standardised
The Xtream-style API is a de facto community convention, not a published specification. Server software implements it independently, so error reporting is not standardised: one server may return HTTP 401 for invalid credentials, another HTTP 200 with an application-level error in the JSON body, a third a blank response. The patterns described here are commonly observed — not definitive for any specific server.
Authentication and Account Status Errors
A request to a server's player_api.php endpoint — if the server supports this pattern — typically returns a JSON response containing an account information section. Two fields are the most commonly observed indicators of authentication status, though neither is guaranteed to be present:
- auth — where present, a value of 1 has commonly been observed to indicate that credentials were accepted; a value of 0 may indicate rejection. This field is not guaranteed to be present on every server, and its type and exact meaning vary between implementations. Some servers signal authentication failure through a different field or structure entirely.
- status — where present, values such as Active, Expired, or Disabled may appear. These are server-defined strings, not a standardised set. A server may use different terminology, include additional states, or omit this field entirely. An Expired or Disabled value does not necessarily mean the credentials themselves are wrong — it indicates how the server has classified the account's current state.
An absent or unexpected auth or status field reflects an implementation difference, not a guaranteed indicator that credentials are invalid.
Common HTTP Errors
HTTP status codes describe the HTTP-level result of the request, while fields in the JSON body represent application-level information returned by the server. A server implementing the Xtream-style player API may return any HTTP status code for reasons only partly related to credential validity. The following are commonly observed in practice, though exact behavior depends on the server:
| Response | What it may indicate | What to check |
|---|---|---|
| 401 Unauthorized | May indicate that authentication failed or credentials were not accepted | Verify username and password; check for copy-paste errors or trailing spaces |
| 403 Forbidden | The server refused the request; may reflect IP restrictions, connection policy, or application-level configuration rather than wrong credentials | Check whether the server requires a specific connection type or IP allowlist; contact your provider |
| 404 Not Found | The expected API endpoint may not exist at this path on this server | Confirm the server address; check that it supports the player_api.php pattern |
| 429 Too Many Requests | Indicates that the client has sent too many requests; it does not establish whether the supplied credentials are valid. | Wait before retrying; avoid sending repeated rapid requests |
| 5xx (Server Error) | Usually indicates a server-side failure. It does not by itself establish whether the credentials are valid. | Retry later or contact the service operator; avoid diagnosing credential validity from a 5xx response alone. |
An HTTP 200 response does not guarantee valid credentials — many servers return HTTP 200 alongside application-level error data in the JSON body.
Empty, Invalid or Unexpected Responses
Not all error conditions appear as HTTP error codes or recognisable JSON. Some server conditions produce responses that are structurally unexpected:
- Blank or empty response — the server returns HTTP 200 with no body, or closes the connection. This can occur due to load or configuration conditions and does not by itself indicate invalid credentials.
- HTML instead of JSON — the server returns a login page, error page, or redirect rather than a JSON object. This typically means the request reached a different service or path than intended, or the server requires a different connection method.
- Empty channel or category lists — the server returns valid JSON with empty arrays. This is an application-level condition and does not indicate authentication failure; credentials may have been accepted but the account may have no content assigned at the server level.
- Malformed or truncated JSON — the response cannot be parsed as valid JSON. This may indicate a server-side error, proxy interference, or a very large response that was cut off. It does not point to a specific condition for your credentials.
When Login Works but Content Does Not
In implementations where those fields carry their commonly observed meanings, an auth value of 1 or a status such as Active may indicate that the server recognised the account. That does not confirm content assignment, subscription scope, concurrent connection availability, or channel entitlement. If credentials appear to succeed but the player shows no content, the cause may lie with account configuration on the server rather than with the credentials themselves.
Player Errors vs Server Errors
Player-facing error messages — 'Login failed', 'Connection error', 'Authentication error' — are player output. They may be generated by the player, mapped from an HTTP or API response, or derived from text returned by the server. Different players may present the same underlying server response differently.
Testing the player_api.php endpoint directly in a browser shows the raw server response and removes the player as a variable. If the direct test returns a response indicating accepted credentials but the player continues to report an error, the next areas to check include player configuration, response parsing, and compatibility between the player and server implementation.