DEV Community

Cover image for Fixing SpotDL OAuth INVALID_CLIENT and 24 Hour Rate Limit Errors (Redirect URI Port Bug)
Douglas MacKrell
Douglas MacKrell

Posted on

Fixing SpotDL OAuth INVALID_CLIENT and 24 Hour Rate Limit Errors (Redirect URI Port Bug)

#spotify #opensource #cli #python

TL;DR

If spotdl --user-auth fails with INVALID_CLIENT or you hit a 24-hour Spotify rate limit (Retry after: 86400s), add this redirect URI to your Spotify Developer App:

http://127.0.0.1:9900/
Enter fullscreen mode Exit fullscreen mode

Then run:

spotdl --no-cache --user-auth "SPOTIFY_URL"
Enter fullscreen mode Exit fullscreen mode

Overview

Recent versions of spotDL use Spotify OAuth (browser-based login) when running with --user-auth. This requires a local callback server and exact redirect URI matching in the Spotify Developer Dashboard.

In this case, spotDL was failing due to:

  • Spotify API returning a 24-hour rate limit (Retry after: 86400s)
  • OAuth redirect URI mismatch between spotDL and Spotify app settings

Once the correct redirect URI was added, authentication succeeded and downloads resumed normally.

Symptoms

1) Spotify Rate Limiting

Terminal output:

Your application has reached a rate/request limit. Retry will occur after: 86400 s
Enter fullscreen mode Exit fullscreen mode

Common causes:

  • Spotify client-credential quota exhausted
  • Shared/default spotDL credentials throttled
  • Spotify penalty window triggered

2) OAuth Redirect Error

Browser error after running --user-auth:

INVALID_CLIENT: Invalid redirect URI
Enter fullscreen mode Exit fullscreen mode

Or after clicking Agree:

Something went wrong
Enter fullscreen mode Exit fullscreen mode

Cause:

Spotify requires redirect URIs to match exactly:

  • Protocol (http vs https)
  • Host (127.0.0.1 vs localhost)
  • Port number
  • Trailing slash

In this case, spotDL attempted to redirect to:

http://127.0.0.1:9900/
Enter fullscreen mode Exit fullscreen mode

But the Spotify app settings only allowed:

http://127.0.0.1:9000/
Enter fullscreen mode Exit fullscreen mode

This mismatch caused OAuth to fail.

Root Cause

spotDL launches a temporary local callback server during OAuth login.

On macOS in this environment:

  • spotDL selected port 9900
  • Spotify app only allowed port 9000
  • Redirect mismatch blocked authorization

Note: The callback port can vary by environment and version. Always match the exact port shown in the browser OAuth URL.

Solution

Add the exact callback URI used by spotDL into your Spotify Developer App settings.

Required Redirect URI

Add the following to your Spotify app:

http://127.0.0.1:9900/
Enter fullscreen mode Exit fullscreen mode

Important:

  • Include http
  • Include port 9900
  • Include trailing slash /

Spotify may display a warning about insecure redirect URIs. This is expected for localhost callbacks and does not prevent functionality.

Step-by-Step Fix

Step 1 — Open Spotify Developer Dashboard

Go to:

https://developer.spotify.com/dashboard
Enter fullscreen mode Exit fullscreen mode

Select your application.

Step 2 — Add Redirect URI

Navigate to:

Edit Settings → Redirect URIs
Enter fullscreen mode Exit fullscreen mode

Add:

http://127.0.0.1:9900/
Enter fullscreen mode Exit fullscreen mode

Click Save.

Step 3 — Run spotDL With User Auth

Use the following command:

spotdl --no-cache --user-auth "https://open.spotify.com/album/ALBUM_ID"
Enter fullscreen mode Exit fullscreen mode

Example:

spotdl --no-cache --user-auth "https://open.spotify.com/album/6pZj4nvx6lV3ulIK3BSjvs"
Enter fullscreen mode Exit fullscreen mode

Step 4 — Complete Browser Authorization

spotDL will:

  1. Open a Spotify login window
  2. Prompt for account permission
  3. Redirect back to the local callback server

Click Agree.

If configured correctly:

  • Browser redirects successfully
  • Terminal resumes execution
  • Album download begins

Optional Diagnostics

Verify Callback Server Is Listening

Before clicking Agree, run:

lsof -nP -iTCP:9900 -sTCP:LISTEN
Enter fullscreen mode Exit fullscreen mode

Expected output:

python3  <pid>  LISTEN  127.0.0.1:9900
Enter fullscreen mode Exit fullscreen mode

If no process is listening:

  • spotDL exited early
  • Another application is already using the port
  • Firewall or security software is blocking localhost callbacks

Command Flow Comparison

Pre-Fix (Broken)

Client Credentials Attempt 

spotdl "https://open.spotify.com/album/..."
Enter fullscreen mode Exit fullscreen mode

Result:

Retry will occur after: 86400 s
Enter fullscreen mode Exit fullscreen mode

OAuth Attempt (Redirect Mismatch) 

spotdl --user-auth "https://open.spotify.com/album/..."
Enter fullscreen mode Exit fullscreen mode

Browser result:

INVALID_CLIENT: Invalid redirect URI
Enter fullscreen mode Exit fullscreen mode

or

Something went wrong
Enter fullscreen mode Exit fullscreen mode

Post-Fix (Working)

Correct OAuth Flow 

spotdl --no-cache --user-auth "https://open.spotify.com/album/..."
Enter fullscreen mode Exit fullscreen mode

Expected behavior:

  • Spotify consent page opens
  • Authorization succeeds
  • spotDL resumes
  • Album downloads successfully

Recommended Stable Usage

To reduce Spotify throttling risk:

spotdl --threads 1 --user-auth "SPOTIFY_URL"
Enter fullscreen mode Exit fullscreen mode

Single-threaded downloads reduce burst API usage and help avoid triggering Spotify rate limits.

Cache Reset (If Problems Reappear)

If spotDL becomes stuck or reuses broken auth tokens:

rm -rf ~/.spotdl ~/.config/spotdl
Enter fullscreen mode Exit fullscreen mode

Then re-run OAuth authentication.

Key Takeaways

  • spotDL now relies on browser OAuth for reliable Spotify access
  • Redirect URI values must match exactly
  • OAuth avoids aggressive Spotify API rate limits
  • Port mismatches are the most common failure cause

Status

OAuth authentication confirmed working after adding:

http://127.0.0.1:9900/
Enter fullscreen mode Exit fullscreen mode

spotDL downloads functioning normally on macOS + Chrome browser.

Related GitHub issue discussion

https://github.com/spotDL/spotify-downloader/issues/2585

Top comments (0)