Skip to main content

​
The success Field

Every response from POST /v1/query includes a success boolean. Always check it first. When success is false:
  • error — a short, human-readable error message.
  • detailedError — extended detail about the failure. May be absent for some error types. For parse errors, it includes the line and column position of the problem.

​
HTTP Status Codes

StatusMeaning
200Request was processed. Check success — SQL errors return 200 with success: false.
400Malformed request body, SQL parse error, or unsupported SQL feature.
401Missing or expired JWT, or token issued by the wrong Cognito pool.
403Missing required scope (query:execute or query:plan) or tenantId mismatch.
429API rate limit exceeded. Retry with exponential backoff.
500Internal server error. Retry with exponential backoff. Include x-request-id when reporting to support.
SQL errors (parse failures, unknown tables, unsupported features) are returned as 200 with success: false, not as 400. A 400 indicates the request body itself was malformed — for example, missing the sql field or sending invalid JSON.

​
Parse Error Example

Request (SQL typo): 
{
  "sql": "SELEKT id, name FROM myschema.users",
  "mode": "execute"
}
Response: 
{
  "success": false,
  "error": "Parse error: unexpected token 'SELEKT'",
  "detailedError": "Parse error at line 1, column 1: unexpected token 'SELEKT'. Expected SELECT, WITH, or a set operation."
}
HTTP status: 400

​
Execution Error Example (200 with success: false)

Request: 
{
  "sql": "SELECT * FROM myschema.nonexistent_table",
  "mode": "execute"
}
Response: 
{
  "success": false,
  "error": "Table not found: myschema.nonexistent_table",
  "detailedError": "No table 'nonexistent_table' exists in schema 'myschema' for this tenant. Check that the table is registered in the portal under Settings > Data Sources."
}
HTTP status: 200

​
The x-request-id Header

Every response from the DynamoSQL Lambda includes an x-request-id response header. Save this value whenever you encounter a 500 error — include it when filing a support request so the DynamoSQL team can locate the relevant logs. 
x-request-id: req_01HZ8KXMR3F9VW2BN6PQYT7GDE

​
Retry Guidance

  • 500s: Retry with exponential backoff (e.g., 1s, 2s, 4s). These indicate a transient server-side failure.
  • 429s: Retry with exponential backoff. You have exceeded the per-tenant API call limit.
  • 400 / 401 / 403: Do not retry. These indicate a client-side error — fix the request, credentials, or token scopes before trying again.
  • 200 with success: false: Do not retry unless the error message suggests a transient condition. Most SQL errors are deterministic and will fail the same way on retry.
When building a wrapper around DynamoSQL, distinguish between HTTP-level errors (non-200 status) and application-level errors (200 with success: false). They require different handling: one is a transport or auth issue, the other is a SQL or schema issue.