Error Handling
Understanding API error responses and status codes
All DataTalk API errors follow a consistent format with an error message and a machine-readable code.
Error Response Format
{
"error": "Human-readable error message",
"code": "MACHINE_READABLE_CODE"
}HTTP Status Codes
| Status | Meaning |
|---|---|
200 | Success |
202 | Accepted — async task created |
400 | Bad Request — invalid input, or the artifact query failed |
401 | Unauthorized — authentication failure |
403 | Forbidden — no API access on the plan, or the operation isn't allowed |
404 | Not Found — resource doesn't exist or no access |
409 | Conflict — the chat to continue can no longer be used |
429 | Too Many Requests — rate limit or tenant spending limit reached |
500 | Internal Server Error — unexpected failure |
502 | Bad Gateway — your database could not be reached |
504 | Gateway Timeout — your database stopped the query for taking too long |
Authentication Errors (401/403)
| Status | Code | Description |
|---|---|---|
| 401 | MISSING_AUTH | No Authorization header |
| 401 | INVALID_AUTH_FORMAT | Header doesn't match Bearer dt_... |
| 401 | INVALID_API_KEY | API key not found |
| 401 | API_KEY_EXPIRED | API key has expired |
| 401 | USER_NOT_FOUND | User associated with the key doesn't exist |
| 403 | TENANT_NOT_FOUND | The key's tenant (organization) no longer exists |
| 403 | INVALID_LICENSE | The tenant's license is not valid |
| 403 | API_ACCESS_DENIED | The tenant's plan doesn't include API access |
Validation Errors (400)
| Code | Description |
|---|---|
VALIDATION_ERROR | Missing or invalid request parameters |
QUERY_ERROR | The database rejected the artifact's SQL query, for example because a table or column changed. Generate a new query. |
For invalid parameters, details lists every issue found (path, message, ...):
{
"error": "prompt is required",
"code": "VALIDATION_ERROR",
"details": [
{ "code": "too_small", "path": ["prompt"], "message": "prompt is required" }
]
}Other examples:
"dbId must be a valid UUID"— malformed database ID"dbId is required when chatId is not provided"— new chat without a database"Artifact must be a SQL artifact"— non-sqlartifact passed to the data endpoint"Artifact has no SQL query"— thesqlartifact has no query to run"Invalid cursor"/"Invalid messageCursor"— the cursor is not anextCursorreturned for this list
Out-of-range pagination values (limit, pageSize, ...) are not errors: they are clamped to the allowed range.
Permission Errors (403)
| Code | Description |
|---|---|
FORBIDDEN | The operation isn't allowed with the current settings or permissions |
DATABASE_PERMISSION_DENIED | The database user DataTalk connects with is not allowed to read a table or column used by the artifact's query. Ask your database administrator to grant it. |
Returned when:
POST /chatis called with"dataAccess": truebut data access is disabled for the tenant or for the database- an artifact's query can no longer run: its owner lost access to the database, or the query uses tables that have been disabled
- the database itself denies the artifact's query a table or column (
DATABASE_PERMISSION_DENIED)
Conflict Errors (409)
| Code | Description |
|---|---|
CHAT_DATABASE_UNAVAILABLE | POST /chat with a chatId that has no database available (for example, its database was removed). Start a new chat instead. |
Resource Errors (404)
| Code | Description |
|---|---|
NOT_FOUND | Resource not found or you don't have access |
This is returned for databases, tables, chats, tasks, and artifacts that either don't exist or belong to another user.
Rate Limits (429)
| Endpoint | Limit |
|---|---|
POST /chat | 10 requests per minute per API key |
| All other REST endpoints | 60 requests per minute per API key |
| MCP server | 60 requests per minute per API key, counted separately |
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time in seconds). Over the limit, the API returns 429 with the code RATE_LIMIT_EXCEEDED and a Retry-After header in seconds.
POST /chat and POST /generate-query also return 429 when the tenant has reached one of its AI spending limits. This body has a different shape:
{
"error": "tenant_cost_limit_exceeded",
"limit_kind": "daily",
"reset_at": "2025-01-16T00:00:00.000Z",
"spent_usd": 10.42,
"limit_usd": 10
}limit_kind is daily, weekly or monthly; retry after reset_at.
Database Errors (502/504)
Returned by GET /artifact/{artifactId}/data (and the MCP get_artifact_data tool) when running the query on your database fails for a reason that isn't the query itself:
| Status | Code | Description |
|---|---|---|
| 502 | DATABASE_UNAVAILABLE | The database could not be reached or refused the connection (offline, wrong credentials, too many connections). Retry later. |
| 504 | QUERY_TIMEOUT | The query hit the database's time limit and was stopped. |
The database's own error message is not returned, because it can contain host names or other internal details.
Internal Errors (500)
| Code | Description |
|---|---|
INTERNAL_ERROR | Unexpected server error |
If you receive this, the issue is on the server side. The error is logged internally.
Handling Errors in Code
const res = await fetch(`${API_BASE}/generate-query`, {
method: "POST",
headers: {
Authorization: `Bearer ${API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ prompt, dbId }),
});
if (!res.ok) {
const error = await res.json();
if (error.error === "tenant_cost_limit_exceeded") {
// The tenant's AI spending limit was reached: retry after error.reset_at
}
switch (error.code) {
case "MISSING_AUTH":
case "INVALID_AUTH_FORMAT":
case "INVALID_API_KEY":
case "API_KEY_EXPIRED":
// Re-authenticate or refresh API key
break;
case "VALIDATION_ERROR":
// Fix request parameters
break;
case "NOT_FOUND":
// Resource doesn't exist or no access
break;
case "RATE_LIMIT_EXCEEDED":
// Wait Retry-After seconds, then retry
break;
default:
// Unexpected error
console.error("API error:", error);
}
}Task Failures
When an async task fails (status FAILED), the error details are in the task's error field, not as an HTTP error. Always check task.status after polling:
const task = await pollTask(taskId);
if (task.status === "FAILED") {
console.error("Task failed:", task.error);
}