Error Glossary

This page is a lookup reference for the errors the ShipHero Public API returns. Use it to go from the message and code you received to the reason the request was rejected and the change that resolves it.

Most failures are not specific to one operation. Before looking up an individual message, check Common causes — authentication, scopes, user permissions, 3PL account access and identifier handling account for the majority of rejected requests. The per-operation tables only document what is specific to that operation.

What is covered on this page:

• Error response shape
• Error codes
  • Throttling and rate limiting
• Common causes
  • Authentication
  • Scopes
  • User permissions
  • 3PL account access
    • Account types
  • Identifiers
• Scope warnings are not errors
• Authentication endpoint errors
• Messages by operation group
  • Orders
  • Products
  • Inventory, locations and LPNs
  • Returns
  • Shipments and shipping containers
  • Purchase orders and shipping plans
  • Cycle counts
  • Totes
  • Lots
  • Wholesale orders
  • Work orders
  • Users
  • Warehouse profiles
  • Experimental API
• Carrier errors on label operations
  • Quoting rates
  • Printing and voiding labels
• Operations gated by internal permissions
• Reporting an error to support

Error response shape

GraphQL always answers with HTTP 200 when the query itself is valid. Failures are reported in the errors array, and the affected field is null in data. A single response can contain several errors.

{
  "errors": [
    {
      "message": "Order not found",
      "operation": "order_update",
      "field": "order_update",
      "request_id": "5da7dc13f3079f0def208711",
      "code": 5
    }
  ],
  "data": {
    "order_update": null
  }
}

Throttling errors use a different set of fields: they carry required_credits, remaining_credits and time_remaining instead of field. See Throttling and rate limiting.

mutation { order_create(data: {order_numberr: "SO-1001"}) { request_id } }
# → { "message": "Field 'order_numberr' is not defined by type 'CreateOrderInput'.",
#     "locations": [{ "line": 1, "column": 31 }] }   // no code, no request_id

Error codes

Codes follow the Google RPC code convention, with a few values added by the Public API.

Codes 3, 5, 6 and 9 mean the request was understood and rejected: retrying it unchanged produces the same result. For errors with codes 10, 14, 21 and 22, the API automatically refunds credits reserved for the failed request. A retry is a new request and is subject to normal credit accounting.

# after a code 22 on order_update, read before you retry
query { order(id: "T3JkZXI6MTIzNDU2") { data { order_number fulfillment_status } } }

Throttling and rate limiting

Two independent limits can reject a request, and they fail in different ways.

Credit quota returns GraphQL error code 30 with required_credits, remaining_credits and time_remaining. Whether waiting helps depends on which limit you hit:

• The operation fits your account maximum but not your current balance — wait time_remaining and retry.
• The operation costs more than your account may spend on a single request — waiting never helps, because the balance can never grow that large. Reduce the request: select fewer fields, lower first, and page through the results.

The decision logic and worked examples are in Example 3: Handle an insufficient-credit error; costs and optimization are covered under Throttling & Quotas.

Request-rate limit is separate and is not a GraphQL error at all. Exceeding 7,000 requests in any five-minute window returns HTTP 429 Too Many Requests with no errors array and no request_id. Failed and introspection requests count toward it. Back off until the window clears — see Request-rate limit.

POST /graphql
# → HTTP 429 Too Many Requests, empty body — nothing to parse as a GraphQL error

Common causes

These causes are not tied to a single operation. They explain most errors, so they are documented once here rather than repeated in every table below.

Authentication

A missing or malformed Authorization header is rejected before GraphQL runs, with HTTP 401 and no error code.

A token can also be well formed and still be rejected because of the state of the user or the account. These are HTTP-level responses with a plain message and no error code.

Scopes

Tokens issued through the OAuth flow carry scopes, and an operation fails with code 7 when the token is missing one.

Some operations need more than one scope. Creating an inbound shipment from an ASN, for example, requires both change:inbound_shipments and change:purchase_orders. See Scopes for the full list.

User permissions

A handful of operations also check whether the ShipHero user behind the token holds a product permission, on top of the token’s scopes: user_update (users.manage.update), warehouse_profile_create (warehouses.manage.create), bill_add_ad_hoc_charge (billing.create), bill_update_ad_hoc_charge (billing.update), and the Experimental billing_charges and billing_rates (billing.manage.read).

Scopes are checked before permissions, so a token missing the scope reports Missing required scope(s): … first and never reaches the permission check.

3PL account access

3PL users act on a customer account by passing customer_account_id. Operations reject an account the token cannot reach with code 7.

mutation { cycle_count_items_create(data: {customer_account_id: "QWNjb3VudDox", ...}) { request_id } }
# → { "message": "User cannot act on behalf of this account", "code": 7 }

mutation { product_update(data: {sku: "ABC", customer_account_id: "QWNjb3VudDox"}) { request_id } }
# → { "message": "Cannot access the requested resource. Permission denied", "code": 9 }

query { product(sku: "NOT-A-SKU") { data { sku } } }
# → { "message": "Product not found", "code": 5 }        // no such record
# → { "message": "Cannot access Location", "code": 7 }    // exists, other account

query { products(customer_account_id: "QWNjb3VudDox") { data(first: 1) { edges { node { sku } } } } }
# → { "data": { "products": { "data": { "edges": [] } } } }   // no errors array at all

Account types

Several errors on this page depend on what kind of account the token belongs to, and no query tells you which kind it is.

This matters most for anything that takes a warehouse_id: on a 3PL client the warehouse belongs to the 3PL, not to the account you are authenticated as. If you are unsure which type you are integrating against, ask the people who contracted the warehouse, or email support@shiphero.com. Guessing from an empty warehouse list is not reliable, because an empty list can also mean an access problem. For help identifying your setup, ask in the ShipHero Community.

Identifiers

Most Invalid id and “not found” errors come from constructing identifiers by hand.

Public API identifiers are Base64 strings that encode an entity type and a number, for example T3JkZXI6MTIzNDU2. Treat them as opaque: do not decode, edit or rebuild them, and do not compare them numerically. To turn a numeric legacy_id into one, use the uuid query rather than encoding it yourself. See Core concepts.

query { order(id: "12345") { data { order_number } } }              # not Base64
query { order(id: "UHJvZHVjdDoxMjM=") { data { order_number } } }   # Base64 of Product:123
# → both: { "message": "Order not found", "code": 5 }

Scope warnings are not errors

When a token lacks the scope required for an individual field, the request still succeeds. The field resolves to null and a warning is reported under extensions.scope_warnings, keyed by <ParentType>.<field_name>.

{
  "data": {
    "order": {
      "id": "T3JkZXI6MTIzNDU2",
      "email": null
    }
  },
  "extensions": {
    "scope_warnings": {
      "Order.email": {
        "code": "FIELD_SCOPE_MISSING",
        "message": "Field 'email' was not resolved because scope(s) 'view:pii' are missing",
        "field_id": "Order.email",
        "parent_type": "Order",
        "field": "email",
        "required_scopes": ["view:pii"],
        "occurrences": 1
      }
    }
  }
}

occurrences counts how many times the field was blocked across the response, so a blocked field inside a list is reported once rather than per item.

Read required_scopes and re-authorize with those scopes if you need the data. If a field you expected comes back null and no error was returned, inspect extensions.scope_warnings before treating it as missing data.

Authentication endpoint errors

The token endpoints are plain HTTP endpoints, not GraphQL. They take a POST with a JSON body and answer with an HTTP status code and a bare JSON string as the body — there is no errors array, no code and no request_id to read.

See Authentication for the full request format.

Messages by operation group

Messages specific to each group of operations. Causes that apply everywhere are in Common causes and are not repeated here.

Orders

mutation { order_create(data: {order_number: "SO-1001", ...}) { request_id } }
# → { "message": "Order with order_number 'SO-1001' already exists", "code": 9 }

Order fulfillment, merging and tracking flows are described in Order Fulfillment and Merge Orders.

Products

Inventory, locations and LPNs

location_bulk_create does not fail on duplicate names. It reports them in skipped_count and skipped_names, so check both fields rather than assuming every location was created. Full walkthrough in Inventory.

Returns

Return flows are described in Returns.

Shipments and shipping containers

Purchase orders and shipping plans

See Purchase Orders.

Cycle counts

See Cycle Counts.

Totes

Lots

See Lots.

Wholesale orders

See Wholesale.

Work orders

Users

Warehouse profiles

Experimental API

Operations on the Experimental API return the same codes. These messages are specific to it. For identifier and cross-account access errors, see Identifiers and 3PL account access.

Carrier errors on label operations

The Experimental API operations that create, quote and void shipping labels call carriers directly. When a carrier rejects a request, the text in the response is the carrier’s own, not ShipHero’s: it can contain JSON, field paths, carrier error codes and provider-specific wording. Treat it as opaque text to surface or log, never as a stable string to branch on.

These errors come from the carrier’s systems, so the codes and common causes above do not classify them. What matters is which channel a given operation reports them through.

Quoting rates

label_quote reports carrier problems as data rather than as GraphQL errors, across three fields:

• errors — top-level quote errors.
• warnings — non-blocking warnings; rates are still returned.
• carrier_errors — per-carrier errors, each entry carrying the carrier and its list of errors.

The include_partial_rates input decides whether a partial failure is fatal. It defaults to false:

• false — if a carrier fails, the mutation fails. You get a GraphQL error and no rates.
• true — successful rates are returned in rates and the failures are reported in carrier_errors alongside them.

Set include_partial_rates: true when quoting several carriers and a usable rate is better than none. A successful response can then still contain carrier failures, so check carrier_errors even when rates is populated.

mutation { label_quote(data: {order_id: "T3JkZXI6MTIzNDU2", include_partial_rates: true, ...}) {
  rates { carrier cost } carrier_errors { carrier errors } } }
# → HTTP 200, rates populated, and carrier_errors: [{ "carrier": "ups", "errors": ["..."] }]

Printing and voiding labels

label_print returns labels and weight_discrepancies. It has no field for carrier errors, so a carrier rejection surfaces as a GraphQL error whose message is the carrier’s raw text. The same applies to label_void, whose label_id must be an outbound ShippingLabel: return and RMA labels are rejected.

Because the message is passed through, the same underlying problem can read differently from one carrier to the next. Common causes worth checking before contacting support:

# a label_print that failed — confirm nothing was created before retrying
query { order(id: "T3JkZXI6MTIzNDU2") { data { shipments { edges { node { shipping_labels { tracking_number } } } } } } }

Operations gated by internal permissions

Appearing in the schema does not mean every token can run an operation. The labor and performance-dashboard operations call Warehouse Hero, a separate ShipHero service that re-authorizes the same user against its own warehousehero.manage.* permissions.

A developer user cannot run these at all. Developer users bypass the Public API’s own permission check and ShipHero’s internal one, but Warehouse Hero has no such bypass, and developer users hold no permissions for it to find. There is no scope, token or request change that gets past this.

The affected operations are pickers_performance_dashboard, packers_performance_dashboard, labor_workers, labor_jobs, labor_worker_activities, labor_activity_start, labor_activity_modify, labor_activity_remove and labor_activity_finish. They surface the rejection as Data is temporarily unavailable. Please try again later, which is why a persistent failure here is not an outage.

To use them, authenticate as a regular ShipHero user who holds the Warehouse Hero permission, rather than as a developer user. Which warehousehero.manage.* permission applies varies by operation and is not visible in the Public API schema, so ask in the ShipHero Community rather than inferring it. Workforce Hero also has to be active for the warehouse, which support@shiphero.com enables.

None of these accept customer_account_id. They always run against the account that owns the token, so a 3PL cannot target a client account with them.

Reporting an error to support

Include the request_id from the error. It identifies your exact request and payload, which is usually enough to explain the failure without a reproduction.

Every query and mutation can also return request_id as a field, so you can capture it on successful operations that behaved unexpectedly:

{
  request_id
  complexity
  orders {
    request_id
    complexity
  }
}

Ask in the ShipHero Community with the request_id. See Error Handling & Support.