IINA's OpenSubtitles integration fails with "Invalid domain" error due to improper redirect handling

[opensubtitlesdev]

Description:

IINA's built-in OpenSubtitles integration is failing to retrieve subtitles when logged in as a VIP user, producing an "Invalid domain" (401) error.

Root Cause:

The OpenSubtitles API enforces alphabetical ordering of query parameters and returns a 301 redirect when they're out of order. IINA's HTTP client either:

1. Does not follow redirects, OR
2. Follows redirects but loses authentication headers or changes the domain incorrectly

Steps to Reproduce:

1. Log into OpenSubtitles with a VIP account in IINA
2. Play any video file
3. Trigger automatic subtitle search
4. Check Console logs

Actual Behavior:

[opensubapi][d] Request: {
"url" : "https://vip-api.opensubtitles.com/api/v1/subtitles?languages=en&moviehash=413142fb64bcd269&query=Frozen.2013.1080p.BluRay.x264.YIFY",
"httpMethod" : "GET"
}
[opensubapi][d] HTTP response status code: 401 unauthorized
[opensubapi][d] Response: {
"errors" : ["Invalid domain"],
"status" : 401
}

Expected Behavior:

The request should either:

1. Send parameters in strict alphabetical order (case-insensitive) to avoid the redirect, OR
2. Follow the 301 redirect while preserving all headers (especially Authorization and Api-Key)

Technical Details:

Testing with curl confirms the issue:

Without following redirects (fails):
curl -v 'https://vip-api.opensubtitles.com/api/v1/subtitles?query=frozen&moviehash=abc123'
--header 'Api-Key: xxx'
--header 'Authorization: Bearer xxx'

Returns: HTTP/2 301

Location: /api/v1/subtitles?moviehash=abc123&query=frozen

(parameters reordered alphabetically)

With redirect following (works):
curl -L 'https://vip-api.opensubtitles.com/api/v1/subtitles?query=frozen&moviehash=abc123'
--header 'Api-Key: xxx'
--header 'Authorization: Bearer xxx'

Returns: HTTP/2 200 (success)

Proposed Solutions:

1. Best practice: Sort query parameters alphabetically (case-insensitive) before making the request to avoid redirects entirely
2. Fallback: Ensure IINA's HTTP client follows 301/302 redirects while preserving all headers

Environment:

• IINA version: 1.4.1
• macOS version: 26.0.1
• OpenSubtitles account: VIP member

[low-batt]

Sorry for the extremely late reply!! I don't work on the plugin and only noticed this issue because I was reporting some problems today.

As of IINA 1.4.0 by default IINA has transitioned to officially supported plugins for accessing Online Media and for downloading subtitles from OpenSubtitles (this plugin).

But this clip from an IINA log file:

[opensubapi][d] Request: {

Indicates the old deprecated implementation built into IINA was used. The old code will be used if the plugin implementation is disabled or uninstalled. Based on that log message, apparently IINA fell back to the builtin implementation. The plugin implementation can be installed using IINA's settings as seen here:

So my question is whether the plugin is working or also has this problem. The plugin doesn't have the same detailed logging and I didn't develop the plugin so I'm unsure how it handles this. I don't have a VIP account to test with.

I can comment on the old code. The params parameter in the API of the HTTP client library IINA is using is a Swift Dictionary which is an unordered collection of key-value pairs. I will have to see if I can figure out a way to get this client library to send query parameters in a specific order.

[low-batt]

After digging into the code of the HTTP client the deprecated IINA client uses I found that although it takes an unsorted dictionary as a parameter it sorts the keys when forming the query string as seen here:

  func query(_ parameters: [String: Any]) -> String {
    var components: [(String, String)] = []
    for (key, value) in parameters.sorted(by: { $0.key < $1.key }) {
        components += self.queryComponents(key, value)
    }

    return (components.map { "\($0)=\($1)" }).joined(separator: "&")
  }

I'm thinking this is not the root cause?:

The OpenSubtitles API enforces alphabetical ordering of query parameters and returns a 301 redirect when they're out of order. IINA's HTTP client either:

1. Does not follow redirects, OR
2. Follows redirects but loses authentication headers or changes the domain incorrectly

I can confirm the old client is not prepared to handle a 301. But the query parameters are properly sorted in the example shown, so why would the server be replying with a redirect? Notice that in the case shown the server did not respond with a 301, it responded with a 401 (Unauthorized):

[opensubapi][d] Request: {
"url" : "https://vip-api.opensubtitles.com/api/v1/subtitles?languages=en&moviehash=413142fb64bcd269&query=Frozen.2013.1080p.BluRay.x264.YIFY",
"httpMethod" : "GET"
}
[opensubapi][d] HTTP response status code: 401 unauthorized
[opensubapi][d] Response: {
"errors" : ["Invalid domain"],
"status" : 401
}

I'm expecting "Invalid domain" means the server thinks this user is not authorized to access the VIP servers? This error response is not discussed in Error codes. Is this how the VIP servers will respond if the user's token has expired? If so, the client is missing code to detect this error and consider the user has having been logged out.

The client is expecting an expired token to trigger a 406 (Not Acceptable) with an "invalid token" message. When it sees that it will consider the user logged out, which includes resetting the REST API location back to "api.opensubtitles.com". This response is also not discussed in Error codes. This server behavior was found through testing.

The documentation doesn't need to cover all error codes, but it should cover special ones that clients need to not just report, but take action on, such as logging back in.

There is an important inconsistency in the documentation with respect to errors. Error codes says this:

5xx Server Error

Sometimes there is 5xx HTTP error, in this case client should re-try same request after 1 second.

But Getting started - Authorization JWT says:

JWT token is valid 24 hours after successfull authentication of user. In response check if JWT is valid (look for HTTP response code 500 with message invalid) otherwise re-authenticate user.

Does the server ever return a 500 "invalid" for an expired token? (side note, "successfull" is a typo)

I can't find it now, but at some point there was a statement that logging in was an expensive operation for the servers. So the client stays logged in and will log out when the user quits IINA. To try and avoid sending requests with an expired token the client treats a token as expired if the user has been logged in for more than 23 hours. It is always ready to drop the token if the server returns a 406 "invalid token".

I can look into adding support for 301/302 redirects, but that doesn't seem to be the root cause of the problem at hand? As a full log was not supplied I can't tell what happened.