Shopify API response status and error codes

When Shopify receives a request to an API endpoint, it returns an HTTP status code with the response headers. On the GraphQL APIs, it also reports failures in the response body, in an errors array.

This page covers both: what each status code means and what to do about it, and how the GraphQL APIs report errors instead.

Anchor to GraphQL error handlingGraphQL error handling

On a GraphQL API, the status code describes the HTTP request, not the operation you asked for. Every GraphQL operation is a POST to a single endpoint, so when Shopify receives that request and answers it, the status is 200 OK — even if the operation inside it failed. The failure is reported in the response body instead, in an errors array:

So a 200 from a GraphQL API means Shopify answered, not that the operation worked. Check for an errors array before treating the response as a success, and read errors[n].extensions.code instead of branching on the status code.

Anchor to Where to find each API's error codesWhere to find each API's error codes

Each GraphQL API documents its own error codes, because the codes and the conditions that produce them differ by API.

The Partner API uses numeric strings for its errors[n].extensions.code values, such as "429" and "500", which match the HTTP status codes on this page. The other GraphQL APIs use symbolic names, such as THROTTLED and INTERNAL_SERVER_ERROR.

The REST Admin API doesn't return an errors[n].extensions.code value. It reports errors through the status codes on this page, with details in the response body's errors or error parameter.

Anchor to Common status codesCommon status codes

The following codes have Shopify-specific causes or remedies. If the code you're looking for isn't here, then see Standard HTTP status codes.

Anchor to [object Object]400 Bad Request

The request wasn't understood by the server, generally due to bad syntax or because the Content-Type header wasn't correctly set to application/json.

This status is also returned when a token exchange request includes an expired or otherwise invalid ID token, and when a request provides an invalid code parameter during the authorization code grant.

Anchor to [object Object]401 Unauthorized

The necessary authentication credentials aren't present in the request or are incorrect.

An expired access token also returns this status, so re-authenticate to obtain a new one. For how long each token lasts, see token lifetimes.

A refresh token that can no longer be used returns this status with the error code invalid_request and the description This request requires an active refresh_token. Treat it as final rather than retrying. See refreshing an expiring offline access token.

Anchor to [object Object]402 Payment Required

The requested shop is currently frozen. The shop owner needs to log in to the shop's admin and pay the outstanding balance to unfreeze the shop.

Anchor to [object Object]403 Forbidden

The server is refusing to respond to the request. On the REST Admin API, this status is generally returned if you haven't requested the appropriate scope for this action.

The GraphQL Admin, Storefront, and Payments Apps APIs report a missing scope differently: the request returns 200 OK with ACCESS_DENIED in errors[n].extensions.code, so don't branch on a 403 to detect one. On the GraphQL Admin API, a 403 means the store has been marked as fraudulent.

Starting January 1, 2027, a request to the GraphQL Admin API or the REST Admin API that presents a public app's non-expiring offline access token also returns this status. The response's errors value contains Non-expiring access tokens are no longer accepted for the Admin API, so you can tell it apart from a missing-scope 403. To stop hitting it, see Migrate to expiring offline access tokens.

Anchor to [object Object]404 Not Found

The requested resource wasn't found, but might be available again in the future.

Anchor to [object Object]422 Unprocessable Entity

The request body was well-formed but contains semantic errors. On the REST Admin API, a 422 can be returned from a variety of scenarios, including, but not limited to:

• Incorrectly formatted input
• Checking out products that are out of stock
• Canceling an order that has fulfillments
• Creating an order with tax lines on both line items and the order
• Creating a customer without an email or name
• Creating a product without a title

The response body provides details in the errors or error parameters.

Anchor to [object Object]423 Locked

The requested shop is currently locked. Shops are locked if they repeatedly exceed their API request limit, or if there's an issue with the account, such as a detected compromise or fraud risk.

Contact support if your shop is locked.

Anchor to [object Object]429 Too Many Requests

The request wasn't accepted because the app has exceeded the rate limit. Learn more about Shopify's API rate limits.

The GraphQL Admin, Storefront, Customer Account, and Payments Apps APIs don't use this status code for rate limiting. They return 200 OK and report it in the response body as a THROTTLED error instead. The Partner API does return 429, with "429" as its errors[n].extensions.code value. See where to find each API's error codes.

Anchor to [object Object]430 Shopify Security Rejection

The request wasn't accepted because it might be malicious, and Shopify rejected it to protect the app from any possible attacks.

On the Storefront API, check that server-side requests include the correct Buyer IP header.

Anchor to Server error codesServer error codes

Shopify returns a 5xx code when it can't complete an otherwise valid request. Most are transient, so retry the request, and check the Shopify status page if the failure persists.

Anchor to Standard HTTP status codesStandard HTTP status codes

Shopify returns the following codes with their standard HTTP meanings.