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

Douglas MacKrell — Sat, 31 Jan 2026 03:05:54 +0000

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/

Then run:

spotdl --no-cache --user-auth "SPOTIFY_URL"

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

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

Or after clicking Agree:

Something went wrong

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/

But the Spotify app settings only allowed:

http://127.0.0.1:9000/

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/

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

Select your application.

Step 2 — Add Redirect URI

Navigate to:

Edit Settings → Redirect URIs

Add:

http://127.0.0.1:9900/

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"

Example:

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

Step 4 — Complete Browser Authorization

spotDL will:

Open a Spotify login window
Prompt for account permission
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

Expected output:

python3  <pid>  LISTEN  127.0.0.1:9900

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/..."

Result:

Retry will occur after: 86400 s

OAuth Attempt (Redirect Mismatch)

spotdl --user-auth "https://open.spotify.com/album/..."

Browser result:

INVALID_CLIENT: Invalid redirect URI

Something went wrong

Post-Fix (Working)

Correct OAuth Flow

spotdl --no-cache --user-auth "https://open.spotify.com/album/..."

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"

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

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/

spotDL downloads functioning normally on macOS + Chrome browser.

Related GitHub issue discussion

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

DEV Community: Douglas MacKrell