GraphQL Admin API - example Throttled request's response

Retired Boards Appdev Graphql Basics And Troubleshooting

Topic summary

Focus: What a throttled Shopify Admin GraphQL API response looks like, including status code and JSON structure.

Key details provided:

  • Body example: errors contains a single item with message “Throttled”. extensions includes cost with requestedQueryCost, actualQueryCost (null when throttled), and throttleStatus (maximumAvailable, currentlyAvailable, restoreRate).
  • Structure clarification: errors, data, and extensions are top-level fields. When throttled, data is absent (or null); only errors and extensions appear.

Status code:

  • One reply states the HTTP status is 429. The original question notes REST docs confirm 429, but GraphQL docs don’t explicitly say so. No authoritative confirmation was posted, but 429 is suggested.

Documentation discrepancy:

  • A participant confirms extensions is not nested inside errors, contrary to the current docs; they assert the docs are wrong and provide a non-throttle error example showing top-level fields.

Open items:

  • A user experiencing throttling when adding product images requested help; no troubleshooting steps were provided.
  • Definitive, documented confirmation of the GraphQL HTTP status code remains unresolved.
Summarized with AI on December 18. AI used: gpt-5.
1

Hello, fellow devs! I’m working on GraphQL Admin API Rate Limit, and the documentation mentions as below:

All requests that are made after the limit has been exceeded are throttled and an {errors: [{ message: “Throttled” }]} error is returned.

Does any of you could share an example response from the request that was throttled? It’s hard for me to exceed the limits as our dev stores do not have enough data (i.e., orders or customers). I’m especially looking for a response body, and status code returned in case of exceeding API limits.

1 Like
2

The status code returned on throttled request should be 429.

3

For sure it’s 429 for Admin REST API, but the documentation doesn’t mention if it’s true for GraphQL API too. Thanks anyway @AddisonApps :slight_smile:

4

Here is an example of a throttled request:

{
   "errors":[
      {
         "message":"Throttled"
      }
   ],
   "extensions":{
      "cost":{
         "requestedQueryCost":202,
         "actualQueryCost":null,
         "throttleStatus":{
            "maximumAvailable":1000.0,
            "currentlyAvailable":118,
            "restoreRate":50.0
         }
      }
   }
}
2 Likes
5

Thanks a ton, @AddisonApps !

6

I am having a throttled error when attempting to add photos to products. Please help.

7

Is the “extensions” object indeed outside of “errors”? The documentation makes it looks like it should be within the error object. Can you confirm or have the documentation updated? Thanks

https://shopify.dev/api/admin-graphql#status_and_error_codes

8

Its definitely outside the documentation is wrong.

I forced an error with a query and this is the result, “errors”, “data”, and “extensions” are all on the top level, though if you have gotten a throttle there wont be “data” just “errors” and " extensions"

{
  "errors": [
    {
      "message": "first cannot exceed 250. To query larger amounts of data with fewer limits, bulk operations should be used instead.\nSee https://shopify.dev/api/usage/bulk-operations/queries for usage details.\n",
      "locations": [
        {
          "line": 2,
          "column": 17
        }
      ],
      "path": [
        "productVariants"
      ]
    }
  ],
  "data": null,
  "extensions": {
    "cost": {
      "requestedQueryCost": 46,
      "actualQueryCost": 2,
      "throttleStatus": {
        "maximumAvailable": 20000,
        "currentlyAvailable": 19998,
        "restoreRate": 1000
      }
    }
  }
}

Cheers,

Gary