DataTalk Docs

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

StatusMeaning
200Success
202Accepted — async task created
400Bad Request — invalid input, or the artifact query failed
401Unauthorized — authentication failure
403Forbidden — no API access on the plan, or the operation isn't allowed
404Not Found — resource doesn't exist or no access
409Conflict — the chat to continue can no longer be used
429Too Many Requests — rate limit or tenant spending limit reached
500Internal Server Error — unexpected failure
502Bad Gateway — your database could not be reached
504Gateway Timeout — your database stopped the query for taking too long

Authentication Errors (401/403)

StatusCodeDescription
401MISSING_AUTHNo Authorization header
401INVALID_AUTH_FORMATHeader doesn't match Bearer dt_...
401INVALID_API_KEYAPI key not found
401API_KEY_EXPIREDAPI key has expired
401USER_NOT_FOUNDUser associated with the key doesn't exist
403TENANT_NOT_FOUNDThe key's tenant (organization) no longer exists
403INVALID_LICENSEThe tenant's license is not valid
403API_ACCESS_DENIEDThe tenant's plan doesn't include API access

Validation Errors (400)

CodeDescription
VALIDATION_ERRORMissing or invalid request parameters
QUERY_ERRORThe 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-sql artifact passed to the data endpoint
  • "Artifact has no SQL query" — the sql artifact has no query to run
  • "Invalid cursor" / "Invalid messageCursor" — the cursor is not a nextCursor returned for this list

Out-of-range pagination values (limit, pageSize, ...) are not errors: they are clamped to the allowed range.

Permission Errors (403)

CodeDescription
FORBIDDENThe operation isn't allowed with the current settings or permissions
DATABASE_PERMISSION_DENIEDThe 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 /chat is called with "dataAccess": true but 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)

CodeDescription
CHAT_DATABASE_UNAVAILABLEPOST /chat with a chatId that has no database available (for example, its database was removed). Start a new chat instead.

Resource Errors (404)

CodeDescription
NOT_FOUNDResource 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)

EndpointLimit
POST /chat10 requests per minute per API key
All other REST endpoints60 requests per minute per API key
MCP server60 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:

StatusCodeDescription
502DATABASE_UNAVAILABLEThe database could not be reached or refused the connection (offline, wrong credentials, too many connections). Retry later.
504QUERY_TIMEOUTThe 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)

CodeDescription
INTERNAL_ERRORUnexpected 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);
}

On this page