Error Reference — VenHub Developer Docs

Error Response Shape

When a request fails, the API returns a JSON body with an error object containing a .tag field with the machine-readable error code, and an error_summary string combining the code and a human-readable message.

JSON — Error Shape

{
  "error": {
    ".tag": "scope_missing"
  },
  "error_summary": "scope_missing/API key missing required scope: inventory:read"
}

Common Errors

These errors can be returned by any endpoint:

Error Code	HTTP Status	Description	Resolution
invalid_api_key	401	API key is missing, malformed, or has been revoked	Check the `X-API-Key` header value. Generate a new key if revoked.
api_key_expired	401	API key has passed its expiration date	Generate a new API key from TINA, the VenHub dashboard.
scope_missing	403	API key lacks the required permission scope	Issue a new key with the required scope, or add the scope to the existing key.
hub_access_denied	403	API key does not have access to the specified hub	Verify the `hub_id` value and that the API key is authorized for that hub.
not_found	404	The requested resource was not found	Check IDs in the path and query parameters.
validation_error	422	Request parameters failed validation	Check the `message` field for which parameter failed and why.

Inventory Errors

Error Code	HTTP Status	Endpoint	Description
hub_not_found	404	/hub_inventory	The specified `hub_id` does not exist
product_not_found	404	Multiple	No product found at the specified location or with the given ID
invalid_location	422	/hubs/product	Cabinet, shelf, or row number is outside the valid range
invalid_quantity	422	/hubs/product/{product_id}/update_quantity	Quantity must be a non-negative integer
invalid_price	422	/product/{product_id}/update_price	Price must be a positive integer in cents

Orders Errors

Error Code	HTTP Status	Endpoint	Description
invalid_cursor	422	/hubs/all_orders_paginated	The provided cursor value is invalid
order_not_found	404	Refund endpoints	The specified order does not exist
already_refunded	409	/orders/{order_id}/refund	Order has already been fully refunded
refund_failed	502	/orders/{order_id}/refund	Payment processor rejected the refund
product_not_in_order	404	/items/{id}/refund	Product UPC not found in the order
insufficient_quantity	422	/items/{id}/refund	Cannot refund more items than were purchased

Handling Errors in Code

Always check the HTTP status code first, then inspect the error field for the specific code:

JavaScript

const res = await fetch("https://tina-api.venhub.com/api/v1/owners/hub_inventory/?hub_id=123", {
  headers: { "X-API-Key": process.env.VENHUB_API_KEY }
})

if (!res.ok) {
  const { error, error_summary } = await res.json()
  const code = error?.[".tag"]

  switch (code) {
    case "invalid_api_key":
    case "api_key_expired":
      // Re-authenticate or alert ops
      break
    case "scope_missing":
      // Missing permission — check API key scopes
      break
    case "hub_access_denied":
      // Wrong hub ID or unauthorized key
      break
    default:
      console.error(`API error: ${code} — ${error_summary}`)
  }
}

✅

For transient failures (network timeouts, refund_failed), implement exponential backoff with a maximum of 3 retries before surfacing the error to the user.