API & SDK Reference

Troubleshooting Common Triple Whale API Errors

This guide covers the most common errors returned by Triple Whale API endpoints and how to resolve them. Find your error code below for likely causes and recommended next steps.

📘

Before You Start

All Triple Whale API requests should be sent to https://api.triplewhale.com/api/v2/... and authenticated with an x-api-key header. Shopify session JWTs and other token types are not supported.

401 — Unauthorized

A 401 response indicates that the request could not be authenticated or authorized. This is almost always related to the API key.

Common Causes

  • Missing header: The x-api-key header is not included in the request.
  • Invalid or revoked key: The API key has been deleted, expired, or revoked.
  • Missing scope: The key is valid but does not include the scope required for the endpoint being called.
  • Wrong token type: A Shopify JWT was sent instead of a Triple Whale API key.

How to Resolve

  1. Confirm the API key is included in the request header as x-api-key: <your-api-key>.
  2. Verify the key is still active under Data > APIs in your Triple Whale account.
  3. Verify scopes by calling GET /api/v2/users/api-keys/me. The endpoint being called requires a key with the matching scope (for example, Orders: Write for order ingestion, Pixel Attribution: Read for the Customer Journey endpoint, Summary Page: Read for Summary Page data, and Data Out for the SQL and Moby endpoints).
  4. If the key looks correct, regenerate it and retest.
📘

Updating a Regenerated Key

When an API key is regenerated, any scripts, integrations, or automations using the previous key must be updated.

403 — Access Denied

⚠️

A 403 Does Not Mean Your Store Lacks API Access

All paid Triple Whale plans include access to the API endpoints they are entitled to. A 403 is almost always about the request payload, not account permissions.

A 403 is most often returned by the Custom SQL and Moby endpoints when the shopId field is missing from the request body or the shop domain is malformed. Other Triple Whale API endpoints return a 400 for the same condition (see the 400 — Bad Request section).

Common Causes

  • Missing shopId: The shopId field is not included in the request body.
  • Malformed shop domain: The shop domain contains extra slashes, is wrapped in a URL, or includes special characters.

How to Resolve

  1. Confirm shopId is present in the request body and formatted as a plain string (e.g. "yourstore.myshopify.com"). No leading or trailing slashes, no URL wrapping.
  2. The 403 response message reads "Access token is required", but on the SQL and Moby endpoints the actual cause is a missing shopId. A clearer error message is on the roadmap.

404 — Not Found

A 404 response indicates that the endpoint URL could not be matched. This is usually a path or method issue.

Common Causes

  • Typo: The endpoint path contains a typo.
  • Deprecated endpoint: The endpoint has been renamed or removed.
  • Wrong HTTP method: A GET request was sent to an endpoint that requires POST, or vice versa.

How to Resolve

  • Verify the endpoint path against the API reference.
  • For SQL queries, use POST /api/v2/orcabase/api/sql.
  • For Moby natural-language queries, use POST /api/v2/orcabase/api/moby.

400 — Bad Request

A 400 response indicates that the request reached the API but could not be processed. The most common causes are missing required fields, invalid field formats, and SQL syntax errors.

Common Causes

  • Missing shop identifier: The shop identifier is required on every endpoint, but its name varies — shopId for the SQL and Moby endpoints, shop for the Customer Journey Attribution endpoint and all Data-In endpoints, and shopDomain for the Summary Page endpoint. Check the endpoint's reference page for the exact field name.
  • Other missing required fields: A required body field is absent. For the SQL endpoint, the required fields are query, period.startDate, period.endDate, and shopId. Other endpoints have their own required fields — see the "Body Params" section of each endpoint's API reference page.
  • Field naming mismatch: A field uses snake_case where camelCase is expected, or vice versa.
  • SQL syntax error: The query contains invalid syntax or references a column or table that cannot be resolved.
  • Invalid date values: Dates are malformed, or startDate is after endDate.

How to Resolve

  • Check field naming. The SQL Builder UI uses snake_case (@start_date / @end_date), but the API expects camelCase (@startDate / @endDate) inside the SQL string, and period.startDate / period.endDate in the JSON body.
  • Check date format. Use YYYY-MM-DD, and confirm startDate is on or before endDate.
  • Validate SQL in-app first. Run the query in the SQL Builder before sending it via the API. If the query works there but returns 400 from the API, double-check the snake_case to camelCase conversion.
  • Verify all required fields. The "Body Params" section of each endpoint's API reference page lists every required field.
  • Avoid SELECT *. Specify the columns you need; schemas are dynamic and SELECT * can produce inconsistent results.

429 — Rate Limit Exceeded

A 429 response indicates that the rate limit has been exceeded. Limits vary by endpoint — refer to the specific endpoint's API reference page for its quota.

Every 429 response includes a Retry-After response header (in seconds) indicating when to retry.

How to Resolve

  • Add backoff. Implement exponential backoff—wait briefly before retrying, and increase the wait if the limit continues to be hit.
  • Break up large jobs. Split wide date ranges into smaller chunks rather than sending a single large request.
  • Space out bulk calls. A small delay between requests in a tight loop is often enough to stay under the limit.
  • Check Retry-After. The header specifies the wait time in seconds.

500 — Internal Server Error

A 500 response indicates that the request failed on the server. While it is a server response, it is often triggered by something fixable on the client side.

Common Causes

  • Unrecognized shop identifier: The shop identifier in the request body does not match a store connected to the Triple Whale account.
  • Transient backend issue: A temporary server-side failure.

How to Resolve

  1. Confirm the shop identifier matches a store connected to the Triple Whale account, exactly (e.g. yourstore.myshopify.com).
  2. Retry once. Transient errors usually clear within a few seconds.
  3. If the error persists, capture the response body and contact support (see below).

Quick Reference Checklist

Before contacting support, run through this checklist. It covers the most common causes of API errors.

  • Is the API key valid, active, and included as x-api-key?
  • Does the key have the scope required for the endpoint being called?
  • Is the shop identifier (shopId / shop / shopDomain depending on the endpoint) present, correctly formatted, and tied to a connected store?
  • Are all required body fields included?
  • Are dates in YYYY-MM-DD format, with startDate on or before endDate?
  • Is the request using the correct path and HTTP method?
  • For SQL: was the query validated in the in-app SQL Builder first?

Contacting Support

If the error persists after working through this guide, contact the Triple Whale support team. Include the following to help resolve the issue quickly:

  • The full error response body
  • The shop domain
  • The endpoint being called
  • The request payload (with the API key redacted)

Updated about 1 month ago

Updated about 1 month ago