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.
| Field | What it is |
|---|---|
code | A 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 |
message | One plain sentence a person can read. It never holds driver text, SQL or host names |
hint | The next step to try |
retryable | true when the same request can work if you send it again |
details.errorClass | The error class, when code is an older code |
ref | The first six characters of the request ID, in capitals. Give it to support, or search for it in Settings > Diagnostics > Logs |
cause | A 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
| Class | Means |
|---|---|
AUTH_TOKEN_EXPIRED, AUTH_TOKEN_INVALID | The token has expired or is not valid. Make a new one |
AUTH_TENANCY_MISMATCH | The request asks for a client the token does not allow |
PERMISSION_DENIED | The role or token cannot do this |
DATASOURCE_UNREACHABLE, DATASOURCE_AUTH_FAILED, DATASOURCE_SSL, DATASOURCE_QUOTA, DATASOURCE_TIMEOUT | The warehouse cannot be reached, refused the credentials, failed TLS, hit a quota or timed out |
DATABASE_NOT_FOUND, DATASOURCE_NOT_FOUND | The database or datasource does not exist |
SQL_SYNTAX, SQL_OBJECT_MISSING, SQL_PERMISSION | The SQL is wrong, names a table or column that does not exist, or the warehouse user cannot read it |
QUERY_TIMEOUT, RESULT_TOO_LARGE | The query took too long, or returned too much |
HASURA_TIMEOUT, HASURA_CONSTRAINT_VIOLATION, HASURA_RLS_DENIED | A Databrain metadata call timed out, broke a rule, or was refused by a row rule |
VALIDATION_FAILED | The request body is not valid |
CONFLICT_CONCURRENT_SAVE | Someone else saved the same object first. Reload and try again |
NOT_FOUND | The object does not exist |
RATE_LIMITED | Too many requests. See Set rate limits |
UPSTREAM_LLM_ERROR | The AI provider did not answer |
UNKNOWN | Something 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:
| Code | Message |
|---|---|
E1001 | Filter or Client variables detected in the query. |
E1002 | Metric data or query could not be found. |
E1003 | Drill-down query execution failed. |
E1004 | Invalid query or insufficient permissions to access it. |
E1005 | An error occurred while fetching data from the database. |
E1006 | Forecast query execution failed. |
E1007 | Hasura server error occurred while processing the request. |
E1005 and E1007 also carry these in details:
| Field | What it is |
|---|---|
details.reason | The exact cause, for example QUERY_TIMEOUT or SCHEMA_TABLE_NOT_FOUND |
details.errorCode | The DBN-* code, with its own page under Error codes |
details.retryable | false when Databrain refused the request itself, so a retry does not help |
details.ref | The same short request reference as ref |
What to do with an error
- Read
messageandhint. - If
retryableistrue, send the request again after a short wait. If it isfalse, fix the request first. - Still stuck: send support the
ref(or thex-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.