OAuth Troubleshooting

Overview

If something goes wrong while connecting an AI client (Claude.ai, an MCP-compatible IDE, or your own client) to the DataLikers MCP server, this page collects the most common error states and the fastest way to resolve each. The OAuth flow is described step-by-step in Connect DataLikers to Claude.ai.

"Authorization failed" or stuck on the consent screen

Symptom: the consent screen at datalikers.com/oauth/authorize shows an error banner instead of the Allow access button, or the page reloads without progressing.

Causes and fixes:

• Missing PKCE code challenge. DataLikers requires PKCE with S256 (RFC 7636); the request must include code_challenge and code_challenge_method=S256. Older clients that send plain are rejected. Update your client or use a Claude.ai version released in 2025 or later.
• Redirect URI mismatch. The redirect_uri you pass must byte-exactly match one of the values registered for the client. https://example.com/cb and https://example.com/cb/ are different. Re-register the client (Dynamic Client Registration is at https://datalikers.com/oauth/register) or fix the URI on your side.
• Unknown client. The client_id does not exist or has been deactivated. Re-run client registration.
• Session expired. If you stayed on the consent page for more than 10 minutes the CSRF nonce expires. Reload the consent screen.

"Token endpoint returned invalid_grant"

Symptom: after consent, your client posts to /oauth/token and gets back {"error":"invalid_grant"}.

Causes and fixes:

• Authorization code expired or already redeemed. Codes are single-use and live for 10 minutes. Restart the flow.
• Wrong PKCE verifier. The code_verifier you POST must match the code_challenge you sent at /oauth/authorize. Most OAuth libraries handle this automatically; if you wrote the flow by hand, double-check that your verifier is the original random string (43–128 URL-safe characters) and not the base64 hash of it.
• redirect_uri does not match. The same redirect_uri used at the authorize step must be sent again on the token exchange.
• Refresh-token reuse. If you submit a refresh token that has already been rotated, OAuth 2.1 requires us to revoke the entire grant family. Re-authorise from the consent screen — your previous tokens are gone for good.

"Rate limit exceeded" (HTTP 429)

Symptom: /oauth/token returns 429 with Retry-After.

DataLikers throttles the token endpoint to 60 requests per minute per client_id. If you cross that threshold:

• Wait the number of seconds in Retry-After before retrying.
• Audit your client for retry storms — most often this is a refresh-token loop that retries on every 5xx without backoff.

MCP tool call returns "invalid_token"

Symptom: the gateway at mcp.datalikers.com/oauth/ returns 401 with WWW-Authenticate: Bearer resource_metadata="..." and the body {"error":"invalid_token"}.

Causes and fixes:

• Access token expired. Access tokens live for 1 hour. Use your refresh token to mint a new one.
• Token was revoked from the Connected Apps page or by an admin. Re-authorise.
• Connection inactive. The DataLikers client account associated with the OAuth client was suspended. Contact [email protected].

If your client supports it, follow the resource_metadata URL in the WWW-Authenticate header — it tells you exactly which authorisation server to talk to.

"Insufficient balance" or 402

Symptom: an MCP tool call returns 402 Payment Required or the response includes a low-balance warning.

OAuth tool calls are billed against the same DataLikers balance as direct Cache API calls. Top up your account at Billing and retry. The OAuth integration does not have a separate sub-balance.

Connected app keeps disappearing from /settings/connected-apps

If a connected app vanishes from the list shortly after authorising:

• Check that your client is calling /oauth/token with grant_type=refresh_token before each access token expires. If the refresh fails (or is never attempted) the access token will expire after 1 hour and the app drops off the active list.
• Check that you haven't disabled the connector on the AI-client side — Claude.ai sometimes surfaces disconnects only on next use.

Still stuck?

Email [email protected] with:

• The exact error and error_description from the OAuth response (or the gateway response, including the WWW-Authenticate header).
• The client_id you used at registration.
• The approximate timestamp of the failed request (UTC, accurate to the minute is plenty).

We log every OAuth event with a correlation ID and can trace the full flow on our side from those three pieces of information.