Skip to Content

Testing & Debugging

Read API and embed errors

Understand the error body the Databrain API returns, and find the right code page fast.

Every failed API call returns one error body. Embeds read the same body and show the message, a Retry and the request ID.

The error body

{
  "data": {
    "error": {
      "code": "DATASOURCE_TIMEOUT",
      "message": "The data source did not answer in time.",
      "hint": "Ask your admin to check that the warehouse is running and reachable.",
      "retryable": true,
      "ref": "7F3A91"
    }
  }
}

Some routes put the object at the top level as error instead of under data.

FieldWhat it is
codeA stable code a program can read. A newer route sends an error class (list below). An older route keeps its own code, such as E1005 or FORBIDDEN, and puts the class in details.errorClass
messageOne plain sentence a person can read. It never holds driver text, SQL or host names
hintThe next step to try
retryabletrue when the same request can work if you send it again
details.errorClassThe error class, when code is an older code
refThe first six characters of the request ID, in capitals. Give it to support, or search for it in Settings > Diagnostics > Logs
causeA more exact cause under the class, when the route knows it. Not always present

The full request ID is in the x-request-id response header.

Error classes

ClassMeans
AUTH_TOKEN_EXPIRED, AUTH_TOKEN_INVALIDThe token has expired or is not valid. Make a new one
AUTH_TENANCY_MISMATCHThe request asks for a client the token does not allow
PERMISSION_DENIEDThe role or token cannot do this
DATASOURCE_UNREACHABLE, DATASOURCE_AUTH_FAILED, DATASOURCE_SSL, DATASOURCE_QUOTA, DATASOURCE_TIMEOUTThe warehouse cannot be reached, refused the credentials, failed TLS, hit a quota or timed out
DATABASE_NOT_FOUND, DATASOURCE_NOT_FOUNDThe database or datasource does not exist
SQL_SYNTAX, SQL_OBJECT_MISSING, SQL_PERMISSIONThe SQL is wrong, names a table or column that does not exist, or the warehouse user cannot read it
QUERY_TIMEOUT, RESULT_TOO_LARGEThe query took too long, or returned too much
HASURA_TIMEOUT, HASURA_CONSTRAINT_VIOLATION, HASURA_RLS_DENIEDA Databrain metadata call timed out, broke a rule, or was refused by a row rule
VALIDATION_FAILEDThe request body is not valid
CONFLICT_CONCURRENT_SAVESomeone else saved the same object first. Reload and try again
NOT_FOUNDThe object does not exist
RATE_LIMITEDToo many requests. See Set rate limits
UPSTREAM_LLM_ERRORThe AI provider did not answer
UNKNOWNSomething else failed on the Databrain side

DBN codes

In the app and in Settings > Diagnostics, an error also has a DBN-<area>-<number> code, for example DBN-QRY-003. Each code has a page that says what it means and what to check. See Error codes.

Older metric codes

Older metric routes still send these codes:

CodeMessage
E1001Filter or Client variables detected in the query.
E1002Metric data or query could not be found.
E1003Drill-down query execution failed.
E1004Invalid query or insufficient permissions to access it.
E1005An error occurred while fetching data from the database.
E1006Forecast query execution failed.
E1007Hasura server error occurred while processing the request.

E1005 and E1007 also carry these in details:

FieldWhat it is
details.reasonThe exact cause, for example QUERY_TIMEOUT or SCHEMA_TABLE_NOT_FOUND
details.errorCodeThe DBN-* code, with its own page under Error codes
details.retryablefalse when Databrain refused the request itself, so a retry does not help
details.refThe same short request reference as ref

What to do with an error

  1. Read message and hint.
  2. If retryable is true, send the request again after a short wait. If it is false, fix the request first.
  3. Still stuck: send support the ref (or the x-request-id), the time and the route. Do not send tokens or customer data.

To find why an embed does not load, see Fix embed problems.