Skip to content
Tutorials
Analytics Query API
Troubleshooting

Troubleshooting

Overview

Errors from this API arrive in two places, and telling them apart is the first step in any diagnosis:

  • HTTP status codes report whether the request was accepted — bad SQL, missing permission, unknown id.
  • The status field in a poll response reports whether the query succeeded. A FAILED query returns HTTP 200, so a client that only checks status codes will mistake it for success.

Submit Errors

400 — request body must be valid JSON

The body was not parseable JSON. Usually a shell quoting problem — single quotes inside a single-quoted -d argument, or an unescaped newline in the SQL.

Build the body with a JSON tool instead of by hand:

terminal
jq -nc --arg sql "SELECT * FROM users_latest LIMIT 10" '{sql: $sql}'

400 — request body must include a non-empty string "sql" field

The sql key is absent, empty, or not a string. Check for a typo in the key name and confirm the value is a JSON string rather than a number or an array.

400 — only read-only SELECT queries are permitted (got ...)

The statement’s first verb is not SELECT. The message names the verb it found. This API accepts a single SELECT only — see SQL rules.

If the verb named is SHOW or DESCRIBE, you are trying to explore the schema. Use Britive Analytics for that.

400 — multiple SQL statements are not permitted

The body contains more than one statement separated by a semicolon. Submit one query per request. A single trailing semicolon is accepted.

400 — invalid query: ...

The statement is a SELECT, but the query engine could not parse it — a syntax error, unbalanced parenthesis, or unknown function. The message relays the engine’s parse error. Test the query in Britive Analytics, then bring the working version back.

403 with a JSON body

The identity does not hold bizintel.analytics.manage. bizintel.analytics.view is not sufficient. Confirm the identity can open Britive Analytics in the console — if it cannot, it cannot use this API either.

403 with an HTML body or no body

A request blocked by Britive’s web application firewall before it reached the API, rather than a permission failure. Very long queries, or queries containing character sequences that resemble an injection attempt, can trigger this.

Try shortening the query. If a legitimate query is consistently blocked, contact Britive support with the query text.

502 — failed to start query

An upstream failure. Retry with backoff. If it persists, contact Britive support with the approximate time of the request.

Polling Errors

404 — unknown query execution id

The id is not one you can poll. Check it against the submit response — a truncated or misquoted id is the usual cause. If the id is correct, the execution has aged out of the query engine’s history.

Resubmit the query to get a fresh id.

502 — failed to check query status

Transient upstream failure. The query itself is unaffected — keep polling. If every poll returns 502, contact Britive support.

502 — failed to generate result download url

The query succeeded but the result URL could not be signed. Poll the same id again; the results are stored, so a retry usually returns a working URL.

Query Failures

These arrive as HTTP 200 with "status": "FAILED" and an error field.

error containsCauseFix
COLUMN_NOT_FOUNDMisspelled or nonexistent columnCheck the column list in Britive Analytics
TABLE_NOT_FOUNDTable name wrong, or not in your schemaConfirm the table in Britive Analytics and reference it unqualified
TYPE_MISMATCHComparing incompatible typesCast explicitly, e.g. CAST(col AS VARCHAR)
Access DeniedQuery referenced something outside your analytics dataReference only tables you can see in Britive Analytics
Query exhausted resourcesQuery scanned too much dataAdd a date filter, select fewer columns, or add a LIMIT

"status": "CANCELLED" means the execution was stopped before completing. Resubmit.

Download Problems

The download_url returns AccessDenied

Two common causes:

  1. The URL expired. It is valid for the expires_in seconds reported when you received it — 300 by default. Poll the same query_execution_id again for a fresh URL; the query does not re-run.
  2. You sent an Authorization header. The URL is already signed. Adding a Britive token makes the storage layer reject the request. Fetch it with no auth header.

The CSV contains only a header row

The query succeeded and matched no rows. Widen the WHERE clause, or confirm the table holds data for the period you filtered on.

The CSV is truncated or corrupt

Confirm the fetch completed rather than timing out mid-download. Large result sets take longer than the default timeout in some HTTP clients — raise it, and write the response to disk in binary mode.

Getting Help

When contacting Britive support, include:

  • The query_execution_id, if the query was submitted.
  • The approximate time of the request, with timezone.
  • The HTTP status code and response body you received.
  • The SQL you submitted, with any sensitive literals removed.

Do not include your token.

Related

Last updated on
API Reference