Frequently asked questions
Why am I being throttled?
The credit pool belongs to the whole account, and every user, token, integration and environment on it draws from the same pool. Most throttling is not caused by too much total traffic: it happens because requests reserve far more credits than they use, or because many requests arrive at the same moment. An integration can be throttled all day while using well under half of what the pool refills in a day. Accounts with a higher limit get throttled too when their queries have these patterns, so a larger pool rarely fixes them on its own.
For how the pool itself works, see Credit quota.
Page sizes larger than the data you get back
ShipHero reserves the estimate before the request runs, and the estimate assumes full pages. A connection with no first or last counts as the default maximum of 100, described under Queries, and nested connections multiply.
Compare extensions.throttling.estimated_complexity with extensions.throttling.cost on your responses. A ratio of 10x or more is the signal:
- A list query estimated at about 500 that usually returns 0-1 records.
purchase_orders(first: 5)with nestedline_items(first: 100): estimated 506, cost 50.- A 10-SKU
productsquery withlocations(first: 100): reserved 2,220 credits, more than half the default pool, and cost 30.
Set first on every connection, including nested ones, close to what you really receive. Fetch large nested lists in a separate, paginated query, and check the result with analyze: true. See Optimizing a Query.
Several jobs hitting the pool at the same time
Throttling arrives in bursts while total daily usage stays moderate, often lining up with another job’s schedule. Look for:
- Scheduled jobs that start on the same minute.
- Webhook-triggered reads running outside the job scheduler.
- Serverless functions or many workers each sending large queries in parallel.
- A forgotten second integration, such as an old connector or a script under an admin’s own login.
- Staging or QA environments using production credentials.
Run jobs sequentially, or share one rate limiter or credit budget across every process. Batch webhook-triggered reads through a queue, for example 10 SKUs per call with aliases, remembering that the costs of all aliased operations in one request are added together before the check. Stagger schedules away from the top of the hour. Inventory every integration using the account’s credentials, since each is a user on the account, and remove what you no longer need. Keep testing on separate credentials, at low volume.
Polling full datasets instead of what changed
Scanning a whole warehouse with item_locations, warehouse_products or locations on every run, or listing all orders or purchase orders with no date filter, reserves credits on every page.
Use updated_from, or date_from on inventory_changes, set to your last successful run with a small overlap. Cache data that rarely changes, such as locations and closed purchase orders. Replace polling with the Inventory Update, PO Update, Shipment Update and Order Allocated webhooks, and use Data Exports for bulk or historical data, which does not use credits.
One request per record, repeated lookups and loops
Fetching each order individually right after listing it, repeating the same lookup dozens of times, or re-reading a purchase order of hundreds of line items whenever one SKU changes all multiply requests against the same pool. So does a pagination loop stuck on one cursor: we have seen one page requested thousands of times with identical variables, every few seconds, for hours.
Request the fields you need in the list query, deduplicate and cache lookups, and make sure pagination stops when pageInfo.hasNextPage is false and that endCursor advances. Log every request’s variables so a loop is visible.
A single request bigger than the whole pool
If the estimate is larger than max_available, the request can never run. The error says that the max allowed for your account is N credits per operation, and time_remaining is 0. Waiting and retrying do not help. Reduce first or split the query, following the pseudo-code in Example 3.
Retrying too soon
A refused request is not charged its estimate, but it still counts toward the request-rate limit, and keeps failing until the credits it needs are restored. We regularly see dozens of retries for every successful request. Wait at least time_remaining before retrying, add jitter, and do not retry the same request from several workers in parallel.
Checking the balance with extra requests
Polling user_quota just to read the remaining credits adds requests of its own. Every GraphQL response already includes extensions.throttling.user_quota with credits_remaining, max_available and increment_rate, alongside cost and cost_detail. Read and log those instead. Note that increment_rate is credits per second.
AI Toolkit requests use their own pool
Requests through the ShipHero MCP or the Public API Skill come from a separate, smaller AI Toolkit credit pool. They do not reduce the standard pool, and the standard pool does not help them.
How can I find which case applies to me?
- Log, for every request: the time in UTC, the operation, the variables, the
request_id,extensions.throttling.estimated_complexity,cost, anduser_quota.credits_remaining. - Group by operation and compare total estimated with total cost. Look for repeated identical variables, and for throttles that cluster at specific minutes.
- List every user and integration that uses the account.
What should I include when contacting support?
Please provide:
- Your ShipHero account ID.
- A few recent
request_idvalues from throttled requests, which return error code30, with their UTC timestamps. - For each
request_id, the job or integration that sent it, and a short description of the business flow. - Which of the causes described in this entry you have already addressed, and what you changed.
Do not include access tokens, refresh tokens, or passwords. We review the account’s usage with you first, and consider a capacity change only after the causes described in this entry have been addressed.
Why do some requests from Google Cloud return HTTP 403 while the same requests work from another network?
If your integration runs on Google Cloud, such as Cloud Run or Cloud Functions, it may send requests from different outbound IP addresses. Some of those addresses may be blocked because of their reputation, causing intermittent HTTP 403 Forbidden responses even when your credentials are valid.
You may notice that:
- The same query and access token work from another network.
- Failed requests return HTTP
403without a GraphQLerrorsarray or arequest_id. - Token requests to
/auth/tokenor/auth/refreshalso return HTTP403from the affected environment.
This pattern can indicate an issue with the outbound IP address. It does not necessarily mean that your token is invalid or that your query has exceeded its credit quota. For credit and request-rate errors, see Throttling & Quotas.
How can I resolve this?
Configure your integration to use a static outbound IP address so its API requests consistently originate from the same address.
- Follow Google’s Static outbound IP address guide for Cloud Run. If you use Cloud Functions, choose the networking configuration appropriate for your function’s generation.
- Verify that requests from your deployed integration use the configured static IP address. Apply this configuration to both GraphQL and authentication requests.
- Retry a request to the ShipHero Public API from that environment.
A static IP address can still be blocked if it has a poor reputation. If HTTP 403 responses continue, contact ShipHero Support with the details below. You may need to use a different static outbound IP address.
Refreshing a valid token or repeatedly retrying the same request will not resolve a blocked outbound IP address.
What should I include when contacting support?
Please provide:
- Your ShipHero account ID.
- The outbound public IP address or addresses used by your integration.
- The timestamps of failed requests, including the time zone, preferably UTC.
- The affected endpoint and HTTP status code.
- Whether the same request succeeds from another network, and a successful
request_idif available.
You can report the issue even if failed requests have no request_id. Do not include access tokens, refresh tokens, or passwords.
Why does the API return “User does not have permissions to access data exports”?
This error means that the user associated with your API request does not have permission to query Data Exports. An administrator must enable Data Exports for that user.
How can I resolve this?
Ask an administrator on your ShipHero account to follow the steps below for the user making the API request.
Regular users
- Sign in to ShipHero Shipping and open the users page.
- Find the user making the API request and click their name to edit their settings.
- Scroll to the bottom of the page to find the API Access section.
- Select Enable Data Exports Access, then save the changes.

Developer users
- Sign in and open the users page.
- Find the developer user making the API request and click Edit under that user.
- In Developer Details, select Enable Data Exports.
- Click Update Developer to save the changes.

After saving the changes, retry the Data Exports query using that user’s credentials.
Why do some shipping labels never show tracking updates?
ShipHero fills tracking_status, delivered and picked_up on each ShippingLabel by polling the carrier. When the label’s carrier is not covered by that pipeline, tracking_status stays UNKNOWN and delivered and picked_up stay null, no matter how long ago the label was created. The request itself succeeds with HTTP 200 and returns no GraphQL errors array, so this is not a problem with your query, your credentials, or the user’s permissions.
The shipments query returns these fields on every label it reports. tracking_status returns one of six values. UNKNOWN, PRE_TRANSIT and TRANSIT mean the label is still in flight; DELIVERED, RETURNED and FAILURE are final and will not change again. The schema types the field as String, so these values do not appear in the schema reference.
Three different situations return UNKNOWN:
- The carrier has no tracking integration yet. Amazon Shipping is the most common case, returned by the API with the carrier
amazon_shipping_api_v2. Generic labels (genericlabel) have no carrier to poll at all. - The carrier’s tracking is temporarily unavailable. Tracking depends on each carrier’s own API, so when that API is retired or stops responding, labels for that carrier stop updating until the integration is rebuilt. USPS retiring its Web Tools API, which also affected Shippo labels, is one example.
- The label has not been scanned yet. For a fully supported carrier,
tracking_statusisUNKNOWNuntil the carrier’s first scan. This one resolves on its own.
Tracking is currently ingested for ups, fedex, dhl_ecommerce, usps_modern, canada_post, canpar, purolator, asendia_one, uni_uni, veho, blue_streak, ontrac, osm, gofo, xdelivery, doordash and international_bridge. Any carrier outside that list returns UNKNOWN.
How can I resolve this?
Use the label’s tracking_number and tracking_url to track the shipment with the carrier directly. Carriers such as UPS accept a public tracking lookup with no account, so this is often faster than waiting for ShipHero to refresh.
No webhook fires when a tracking status changes: the Shipment Update webhook fires once when the order is fulfilled and gives you the tracking number for each package. If you poll instead, query only the labels that are not yet in a final status and stop once they get there. The underlying data refreshes about hourly, so polling faster than that gains nothing.
Check the Changelog for the announcement when a carrier’s tracking becomes available.