Skip to content

Error Handling

Jump to bottom
Shashank Patil edited this page Jul 26, 2026 · 1 revision

Error Handling

The Generic SQL API Framework provides structured error responses to help developers quickly identify and resolve issues.

Every error response follows a consistent JSON format.

Error Response Format

{
    "success": false,
    "message": "Error description."
}

Common Errors

Invalid JSON Request

Cause

The request body contains malformed JSON.

Example

{
    "query": "customers",

Response

{
    "success": false,
    "message": "Invalid JSON format."
}

Query File Not Found

Cause

The requested SQL file does not exist.

Request

{
    "query": "customer_list"
}

Framework searches for

queries/customer_list.sql

Response

{
    "success": false,
    "message": "Query file not found."
}

Solution

  • Verify the SQL file exists.
  • Check the query name.
  • Ensure the file extension is .sql.

Missing Required Parameter

SQL

SELECT *
FROM CustomerTable
WHERE CustomerID = :CustomerID;

Request

{
    "query": "customer_by_id"
}

Response

{
    "success": false,
    "message": "Missing required parameter: CustomerID"
}

Solution

Include all required parameters.

Database Connection Failed

Response

{
    "success": false,
    "message": "Database connection failed."
}

Possible Causes

  • SQL Server is offline
  • Incorrect server name
  • Invalid credentials
  • Firewall restrictions
  • ODBC Driver not installed

SQL Execution Failed

Response

{
    "success": false,
    "message": "SQL execution failed."
}

Possible Causes

  • SQL syntax error
  • Missing table
  • Missing column
  • Permission denied

Validation Failed

Response

{
    "success": false,
    "message": "Validation failed."
}

Possible Causes

  • Invalid request structure
  • Unsupported property
  • Invalid pagination values
  • Invalid sorting direction

Unauthorized Access

Response

{
    "success": false,
    "message": "Unauthorized request."
}

Possible Causes

  • Missing authentication
  • Invalid API key
  • Access denied

HTTP Status Codes

Status Description
200 Request completed successfully
400 Bad request
401 Unauthorized
404 Query file not found
500 Internal server error

Debugging Checklist

Before reporting an issue, verify the following:

  • SQL Server is running.
  • Database credentials are correct.
  • ODBC Driver is installed.
  • SQL query executes successfully in SQL Server Management Studio.
  • JSON request is valid.
  • Required parameters are included.
  • SQL file exists in the queries directory.

Logging

When debugging, review the application logs for:

  • Request details
  • Validation failures
  • SQL execution errors
  • Database connection errors
  • Stack traces (development mode)

Tip: Avoid exposing detailed error messages or stack traces in production. Log them internally and return a generic message to clients.

Best Practices

  • Validate requests before sending them.
  • Use parameterized queries.
  • Return consistent error responses.
  • Monitor application logs regularly.
  • Handle errors gracefully in client applications.

Next Steps

Continue with:

  • Performance Tips
  • Security Best Practices
  • Framework Architecture
  • Contributing

Clone this wiki locally