Common Shopify Error Codes and How to Fix Them (2026)

A Complete Reference for Every Shopify Error You Will Encounter

Shopify error codes are the platform's way of telling you something went wrong — but the messages themselves are rarely helpful. A "500 Internal Server Error" does not tell you whether an app crashed, your theme code is broken, or Shopify's servers are on fire.

This guide decodes every common Shopify error code and gives you a concrete fix for each. Whether you are a merchant troubleshooting your own store or a developer debugging for a client, bookmark this page as your go-to reference. For more diagnostic walkthroughs, browse our full troubleshooting category.

Understanding these error codes matters because they fall into distinct categories — client errors (400-level), server errors (500-level), and Shopify-specific codes — and each category points to a fundamentally different type of problem.

HTTP 400-Level Client Errors

400-level errors mean the request from the browser (or API client) was invalid. The problem is on the client side, not with Shopify's servers.

Error 400: Bad Request

The server could not process the request because the syntax was malformed. On Shopify storefronts, this typically appears when:

• A form submission contains invalid data — checkout forms with special characters in address fields, or product option selectors with corrupted values
• A URL contains invalid parameters — malformed query strings from tracking links or app-generated URLs
• A script sends a broken AJAX request — custom JavaScript or a third-party app sending incorrectly formatted data

How to fix it:

1. Check the URL for obvious issues (double slashes, broken query parameters, encoded characters)
2. Open browser developer tools (F12 > Network tab) and inspect the failing request to see exactly what was sent
3. If the error occurs on a form, test with simple data to rule out special character issues
4. If a third-party app generates the URL, contact the app developer

Error 401: Unauthorized

This error rarely appears on the storefront but is common in API integrations and app development. It means the request lacks valid authentication credentials.

Common causes:

• Expired or revoked API access token
• Missing X-Shopify-Access-Token header in API requests
• App permissions were changed after the token was issued

How to fix it: Regenerate the access token in your Shopify admin under Settings > Apps and sales channels, or re-authenticate the app.

Error 403: Forbidden

The server understood the request but refuses to fulfill it. On Shopify, this usually means:

• Geographic restrictions — your store blocks certain countries, and a visitor from a blocked region is trying to access it
• IP-based blocking — a fraud prevention app or Shopify's own systems blocked the IP
• Bot protection — Shopify's bot detection flagged automated traffic

How to fix it:

1. Check Settings > Markets to see if you are restricting access by region
2. Review any fraud prevention or firewall apps for overly aggressive blocking rules
3. If legitimate customers report 403 errors, ask for their IP address and check your blocking lists

Error 404: Page Not Found

The most common error code on any website. On Shopify, a 404 means the requested URL does not match any existing page, product, collection, or blog post.

Common causes and fixes:

Creating URL redirects in Shopify:

1. Go to Online Store > Navigation > URL Redirects
2. Click Create URL redirect
3. Enter the old URL path in "Redirect from" and the new path in "Redirect to"
4. Save

Shopify's guide to URL redirects explains the full process including bulk imports for large migrations. Remember that you cannot redirect from URLs that still resolve to a valid page — only from URLs that return a 404.

Error 429: Too Many Requests

This error appears when your store exceeds Shopify's API rate limits. It primarily affects apps and custom integrations rather than regular storefront browsing.

Rate limit thresholds:

• REST Admin API: 40 requests per app per store per minute (standard plans), higher for Plus
• Storefront API: 100 requests per second per IP
• GraphQL Admin API: Uses a cost-based system with a bucket that refills over time

How to fix it:

• Reduce API call frequency — batch operations where possible instead of making individual calls
• Implement retry logic with exponential backoff — when you get a 429, wait and retry with increasing delays
• Cache responses — store frequently accessed data locally instead of fetching it every time
• Audit apps — some apps make excessive API calls that eat into your rate limit

According to Shopify's API response code documentation, the Retry-After header in a 429 response tells you exactly how many seconds to wait before retrying.

HTTP 500-Level Server Errors

500-level errors mean something went wrong on the server side. These are more serious and often harder to diagnose because the root cause is not always under your control.

Error 500: Internal Server Error

The catch-all server error. On Shopify, a 500 error usually points to:

• Broken Liquid code in your theme that causes the server-side renderer to crash
• An app injecting bad code into a page template
• A corrupted product or page — bad data from a CSV import or bulk edit
• Temporary server-side issue on Shopify's infrastructure

Diagnostic steps:

1. Switch to a default theme (Dawn) temporarily — if the error disappears, your theme code is the problem
2. Disable third-party apps one by one to isolate app conflicts
3. Check if the error is page-specific — if only one product page throws a 500, the product data might be corrupted
4. Clear browser cache and retry
5. **Check shopifystatus.com** for platform-wide incidents

Brainspate's guide to Shopify server errors provides additional diagnostic patterns for persistent 500 errors.

Error 502: Bad Gateway

A 502 means Shopify's edge server received an invalid response from an upstream server. This is almost always a Shopify infrastructure issue, not something you caused.

What to do:

1. Wait 2-5 minutes and refresh — 502 errors are usually transient
2. **Check shopifystatus.com** for active incidents
3. Try from a different network — some ISPs may be experiencing routing issues to Shopify's servers
4. If the error persists for more than 15 minutes and the status page shows no issues, contact Shopify Support

Error 503: Service Unavailable

The server is temporarily unable to handle the request, usually because it is overloaded or undergoing maintenance.

On Shopify, 503 errors occur during:

• Platform maintenance windows — Shopify will usually announce these in advance
• Extreme traffic spikes — though Shopify's infrastructure handles most surges, individual store resources can be strained
• App-caused resource exhaustion — an app performing heavy operations can temporarily make a store unresponsive

How to fix it: Most 503 errors resolve within minutes. If yours does not, check the status page and disable recently installed apps.

Error 504: Gateway Timeout

The server did not receive a timely response from an upstream server. This is similar to a 502 but specifically about timeout rather than an invalid response.

Common causes on Shopify:

• Complex Liquid templates that take too long to render — loops over large collections without pagination
• Heavy API operations triggered by apps during page load
• Database queries timing out on stores with massive product catalogs (100,000+ products)

How to fix it:

1. Simplify your Liquid templates — replace {% for product in collections.all.products %} with paginated queries
2. Reduce the number of products displayed on collection pages
3. Audit apps that run server-side operations on page load
4. Contact Shopify Support if 504 errors happen consistently on specific pages

Shopify-Specific Error Codes

Beyond standard HTTP status codes, Shopify uses several platform-specific codes.

Error 540: Temporarily Disabled

This is a Shopify-proprietary status code indicating that a store, resource, or endpoint has been temporarily disabled. According to AtomSEO's analysis of Shopify response codes, it can occur due to:

• Scheduled maintenance on Shopify's infrastructure
• Security protocols — Shopify may disable a store in response to detected threats
• Resource limitations during peak traffic periods
• Account or billing issues that trigger a temporary suspension

How to fix it:

1. Wait 15-30 minutes — this error often resolves on its own
2. Check your email for any communications from Shopify about your account
3. Verify your billing is current in Settings > Plan
4. Contact Shopify Support if the error persists beyond an hour

"Sorry, This Shop Is Currently Unavailable"

This is not a numbered error code but one of the most common Shopify error messages. It appears when:

• Your Shopify plan has expired or been paused
• Your store was deactivated (voluntarily or by Shopify for policy violations)
• You are on a development store without a paid plan

How to fix it: Log into your Shopify admin at your-store.myshopify.com/admin and check your plan status under Settings > Plan. If your plan lapsed, reactivate it.

Checkout "Unable to Process" Errors

These errors appear during the payment step and cover a range of issues from card declines to gateway timeouts. For a complete deep-dive, see our dedicated guide on how to customize Shopify checkout and ensure your payment flow is correctly configured.

Liquid Template Errors

Liquid errors are the most common code-level issues on Shopify. They do not always produce HTTP error codes — sometimes they result in broken layouts, missing content, or blank pages.

Syntax Errors

Liquid syntax errors happen when your template code violates the language rules. Shopify's Theme Check documentation identifies these as the most frequently caught issues:

How to find and fix Liquid errors:

1. Check your Shopify admin — Liquid errors often show in the theme editor with line numbers
2. Install the Shopify Liquid VS Code extension for real-time syntax highlighting
3. Run shopify theme check via the Shopify CLI to lint your entire theme
4. Use {% comment %} and {% endcomment %} to comment out suspect code blocks and narrow down the issue

Memory Limit Errors

Shopify imposes memory limits on Liquid rendering. If your template is too complex — deeply nested loops, huge collections loaded without pagination, or excessive variable assignments — you will hit a memory limit error.

How to fix it:

• Paginate collection pages instead of loading all products at once
• Use `limit` on for loops — {% for product in collection.products limit: 20 %}
• Avoid nested for loops over large datasets
• Move complex logic to metafield pre-computation or app-based calculations

"Could Not Find Asset" Errors

This error appears when a Liquid template references a file (CSS, JavaScript, image, or snippet) that does not exist in your theme.

Common triggers:

• You deleted a file that is still referenced in the theme
• An app was uninstalled but its asset references remain in your theme code
• A theme update removed a file that your customizations depend on

How to fix it:

1. Search your theme files for the referenced filename
2. Either re-upload the missing asset or remove the reference
3. After uninstalling apps, always search your theme for leftover {{ 'app-name' | asset_url }} references

Image and Media Errors

Image-related errors are common on Shopify, especially during bulk product uploads.

Upload Size Limits

Shopify enforces a maximum file size of 20 MB per image. Additionally:

• Maximum image dimensions: 4472 x 4472 pixels (or 20 megapixels)
• Accepted formats: JPEG, PNG, GIF, WebP, HEIC, AVIF
• SVG is allowed for theme assets but not for product images

If an image upload fails, compress and resize it before retrying. Tools like TinyPNG or Squoosh handle this in seconds.

Broken Product Images

If product images appear broken (show a placeholder or do not load):

• Check the file URL — it may have been deleted from Shopify's CDN
• Re-upload the image through the product editor
• Verify the image is not corrupted — open it locally to confirm it renders correctly

For best practices on image optimization that prevent errors and improve page speed, see our guide on Shopify store speed optimization.

API and Integration Errors

If you use custom apps, private integrations, or headless commerce setups, API errors are part of the landscape.

Authentication Errors (401 / 403)

API calls require valid access tokens with the correct scopes. If your integration suddenly stops working:

1. Check if the access token expired — some tokens have expiration dates
2. Verify scopes — if Shopify added new required scopes for an endpoint, your existing token may lack permission
3. Regenerate the token from your app settings in the Shopify admin

Rate Limiting (429)

As covered in the 400-level section, API rate limits are per-app, per-store. If multiple apps share the same API, they compete for the same rate limit bucket. Shopify's API documentation provides exact bucket sizes and refill rates for each API type.

Best practices for avoiding rate limits:

• Use GraphQL instead of REST — it is more efficient and uses cost-based rather than count-based limiting
• Implement webhook subscriptions instead of polling for changes
• Cache responses aggressively on your end
• Use bulk operations for large data imports/exports

Webhook Delivery Failures

Shopify retries failed webhook deliveries for up to 48 hours. If your endpoint is consistently failing:

• Check your server logs for the incoming webhook requests
• Verify your webhook URL is publicly accessible (not localhost or behind a VPN)
• Confirm your endpoint returns a 200 status within 5 seconds — Shopify considers anything else a failure
• Check for payload size issues — some webhooks carry large payloads that overwhelm underpowered servers

CSV Import and Bulk Operation Errors

Bulk imports via CSV are a common source of data corruption that leads to downstream errors.

Common CSV Import Issues

Recovering from a Bad Import

If a CSV import corrupted your product data:

1. Export your current products as a backup
2. Identify corrupted entries by checking for missing images, wrong prices, or broken descriptions
3. Fix the data in the CSV and re-import using the "Overwrite existing products" option
4. Check your storefront for any products showing errors or missing data

For stores just getting started, our guide on how to start a Shopify store covers proper initial data setup to avoid these issues from the beginning.

Common Mistakes When Handling Error Codes

Even experienced developers make these mistakes when troubleshooting Shopify errors.

Ignoring the Specifics

A 502 and a 504 look similar ("something broke on the server"), but they have different causes and different fixes. A 502 is a bad upstream response — usually Shopify's problem. A 504 is a timeout — often caused by your theme code. Treat them differently.

Fixing Symptoms Instead of Causes

Refreshing a page that throws a 500 error might make it work temporarily, but the underlying broken code is still there. Find and fix the root cause — do not just retry until it works.

Not Checking Across Pages

An error on one product page might mean corrupted data on that specific product, not a site-wide issue. Test multiple pages before concluding the entire store is broken.

Building an Error Monitoring System

Do not wait for customers to report errors. Set up monitoring to catch problems proactively.

Shopify's Built-In Tools

• Online Store > Themes > Actions > Edit Code — Liquid errors show inline with line numbers
• Analytics > Reports — check for spikes in 404 errors
• Settings > Notifications — configure admin alerts for failed orders

External Monitoring

For more comprehensive monitoring:

• Google Search Console — reports crawl errors, 404s, and server errors that Google encounters on your store
• Shopify's web performance dashboard — tracks Core Web Vitals and loading issues using real user data
• Uptime monitoring tools — services like Uptime by Shopify or third-party tools like Pingdom can alert you immediately when your store goes down

Run your store through Google PageSpeed Insights monthly to catch performance regressions before they become errors. For guidance on interpreting and acting on those results, read our Core Web Vitals optimization guide.

Logging and Alerting Best Practices

If you run custom apps or headless integrations:

• Log all non-200 responses with timestamps and request details
• Set up alerts for error rates above your baseline — a sudden spike in 500 errors means something just broke
• Track error rates by page — if one product page consistently throws errors, the issue is likely bad data, not bad code
• Review logs weekly — patterns emerge over time that are invisible in individual error reports

Quick Reference: Every Shopify Error Code at a Glance

Use this table as a rapid-lookup guide when you encounter an error.

Stop Guessing, Start Diagnosing

The difference between a merchant who panics during an error and one who resolves it in minutes comes down to understanding what each common Shopify error code means and how to fix it. Every code in this guide points to a specific category of problem with a specific diagnostic path.

Build the habit of checking the status page first, the browser console second, and your theme code third. Keep this reference bookmarked for the next time you see a cryptic error — and share it with your team so everyone knows the drill.

What is the most frustrating Shopify error you have encountered? Drop it in the Talk Shop community and let's solve it together.

About Talk Shop

The Talk Shop team — insights from our community of Shopify developers, merchants, and experts.