Shopify OAuth Errors: Codes, Causes & Fixes

A required parameter is missing or malformed. Most often: missing client_id, empty scope, missing redirect_uri, or a shop parameter that isn't a valid *.myshopify.com domain.

Inspect your authorization URL parameter by parameter. Required: client_id, scope (comma-separated, no spaces), redirect_uri (must exactly match what's registered in the app settings, including trailing slashes), state (your CSRF nonce), and a valid shop. Compare against a known-working URL.

The client_id and/or client_secret in your token-exchange request don't match a real Shopify app, or you copied the wrong app's credentials.

In your Dev Dashboard, open the app's API credentials page and copy the Client ID and Client Secret again. Be careful not to copy whitespace. Verify you're using the credentials of the same app that initiated the authorization request.

A scope name is misspelled, doesn't exist, or you're requesting a protected scope (like read_all_orders) without approval.

Scope names are case-sensitive snake_case (read_products, write_orders). See the complete scope reference for valid names. For protected scopes, apply for access through your Partner Dashboard before requesting them.

The redirect_uri in your authorization request doesn't exactly match any URL listed in the app's Allowed redirection URLs.

Open your app settings on the Dev Dashboard and verify the Allowed redirection URLs list. The match is exact: scheme, host, port, path, and trailing slash all matter. http://localhost:3000/callback and https://localhost:3000/callback are different. Add the URL you're actually using.

The HMAC signature Shopify sends covers the rest of the query parameters, signed with your client secret. Mismatch usually means you're hashing the wrong string or using the wrong secret.

Build the message to hash from all query parameters except hmac and signature, sorted alphabetically, joined as key=value pairs with & separators. Do not URL-encode. Hash with HMAC-SHA256 using your client secret. Compare hex-to-hex. Most bugs are: leaving hmac in the input, double-URL-decoding values, or using the wrong app's secret.

The shop parameter must be a valid *.myshopify.com domain (the canonical one, not a custom domain). Subdomains, custom domains, and trailing paths all fail.

Always resolve the merchant's input to its canonical *.myshopify.com domain before building the OAuth URL. If the user types a custom domain like example.com, you can resolve it via a HEAD request to https://example.com and following redirects to find the .myshopify.com canonical.

The merchant clicked Cancel on the consent screen instead of approving the install. This is user behavior, not a bug.

There's no programmatic fix. Reduce your scope requests (merchants reject installs that ask for too much), improve your in-app messaging that explains why you need each scope, and let the user retry the flow.

The authorization code is single-use, expires after roughly 10 minutes, and is bound to the exact client_id and redirect_uri that requested it. You're either reusing a code, exchanging it too late, or sending mismatched parameters.

Exchange the code immediately on callback, server-side. Never store the code for later. Never retry a failed exchange with the same code — start the flow over. Confirm client_id and redirect_uri in the exchange match what was used in the authorize request.

Either someone is replaying an old callback URL, your state-storage cookie expired or didn't make the round-trip, or you're storing state per-tab and the user opened the consent screen in a different tab.

Treat state mismatch as a real CSRF rejection — refuse the callback. If users hit this legitimately, extend your session storage TTL beyond the OAuth window, store state in a cookie that survives navigation, and make sure your cookie's SameSite policy doesn't strip it on cross-site redirects.

Something went wrong on Shopify's side. Usually transient.

Retry once after a short backoff (1–5s). If it persists for more than a few minutes, check status.shopify.com. Don't loop indefinitely — show the user an error and let them retry manually.

Shopify is rate-limiting or in maintenance. Sometimes also returned by upstream load balancers under load.

Back off and retry with exponential backoff capped at a few minutes. Surface a friendly retry-later message to the merchant.

Token has been revoked (merchant uninstalled), you're using the token against the wrong shop, you're sending it on the wrong header, or the token format is mangled.

Send the token only on the X-Shopify-Access-Token header, not Authorization: Bearer. Verify you're calling /admin/api/<version>/... on the same shop the token was issued for. If the merchant uninstalled, you must re-run OAuth on next install.

Token is valid but doesn't include the scope required for the resource you're calling. For example, calling /products.json with only read_orders.

Re-run the OAuth flow with the missing scope added to your scope list. Existing tokens never auto-expand — the merchant must re-approve.

The merchant's Shopify plan is frozen or overdue. Their store is in a paused/locked state.

There's nothing the app can do. Surface a friendly notice to the merchant pointing them to their Shopify billing.

When a merchant uninstalls, all access tokens for that shop are immediately revoked. Reinstall issues a brand-new token — the old one stays revoked.

Listen for the app/uninstalled webhook to clean up stored tokens. On reinstall, capture the new token from the OAuth callback. Don't try to refresh — Shopify Admin API offline tokens don't have a refresh endpoint. See the rotation guide for the safe re-issue procedure.

The store is temporarily locked, often during a Shopify-initiated security review or a fraud check.

There's no client-side fix. The merchant has to resolve the lock with Shopify. Pause writes and surface the situation to the merchant.