Troubleshooting Halo Cloud

This guide provides troubleshooting steps for Halo Cloud.

General troubleshooting approach

1. Identify error pattern: Is this a one-off error or recurring issue?
2. Apply the appropriate strategy:
   • 4xx errors: Fix the underlying issue before retrying
   • 5xx errors: Use exponential backoff and retry
3. Contact support: For persistent issues or if you need clarification
4. Pause queries based on context: For example, pause querying unavailable resources such as doctors that are away on holiday.
5. Reduce unnecessary queries: This minimizes billing costs and reduces the load on practice servers.

Error Responses

General

{
  "status": 400,
  "statusText": "Bad Request",
  "message": "Halo GUID must be provided."
}

Queries

Failed queries return additional error data using the following format:

{
  "errorDetails": {
    "errorType": "http",
    "errorCode": 413,
    "errorMessage": "Query was executed successfully but an error occurred preparing it to be uploaded, results were too large. Immediate query results beyond message size limit (8mb)"
  }
}

The errorType field indicates the type of error that occurred and can help narrow down the cause of the issue.

Error Type	Details
mssql	A Microsoft SQL server error occurred. This generally indicates a SQL query issue.
fbsql	A Firebird SQL error occurred. This generally indicates a SQL query issue.
http	A HTTP related error occurred while transferring data from the site.
haloLink	An unexpected error has occurred while transferring data from the site. Contact support if the issue persists.

FHIR OperationOutcome Format

FHIR queries may also return errors as OperationOutcome resources:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "fatal",
      "code": "exception",
      "details": {
        "coding": [
          {
            "system": "http://hl7.org/fhir/dotnet-api-operation-outcome",
            "code": "5003"
          }
        ],
        "text": "Unable to parse Resource URL"
      }
    }
  ]
}

Query Types and Error Behavior

API	Query Type	Error Handling
SQL Passthrough	Immediate	Errors returned directly in HTTP response.
SQL Passthrough	Async	Errors in HTTP response (pre-execution) or query result (during/post-execution).
SQL Passthrough	Registered	As above, with HTTP response errors indicating that registration failed.
FHIR API	FHIR queries	HTTP errors plus FHIR OperationOutcome resources.

Halo Cloud passes through database error messages where possible, allowing you to adjust your application logic accordingly.

Known Issues

SQL Passthrough Issues

Parameter Conversion Failures

Problem: Stored procedure queries with VarBinary or NVarChar parameters return 400 errors when values exceed size limits.

Root Cause: Implicit conversion fails for:

• VarBinary: Arrays > 8,000 bytes
• NVarChar: Strings > 4,000 characters

Solution: Use explicit SQL with variable declarations instead of storedProcedure type:

{
  "command": {
    "text": "DECLARE @Content VarBinary(max); SET @Content = 0xEFBBBF54686973206973206120746573742066696C652E; EXECUTE @returnValue = sp_InsertSampleDocument @Content=@Content; SELECT @ReturnValue",
    "executionMode": "reader",
    "type": "text"
  }
}

HTTP error codes

The following section covers common HTTP error codes you may encounter when using Halo Cloud APIs, their typical causes, and recommended actions.

200 success

A HTTP response of 200 means the POST succeeded. However, that means different things for different query types:

• Immediate and FHIR queries: the query was successfully received, executed, and sent back to the integrator.
• Async and registered queries: the query was successfully received and queued for execution.

Important: Async and registered queries may still error during execution or upload, in which case the error will be made available via the Get query result endpoints.

4xx client errors

4xx errors indicate issues with the API request. These typically require action on your side to resolve.

Code	Common Causes	Examples		Recommended Actions
400	Invalid API Request • Missing required query parameters • Invalid request body format • Malformed JSON payload SQL Query Issues • Malformed SQL syntax • Invalid column/table names • Parameter type mismatches • Query execution failures	• Login failed for user [userID] • Required parameter 'practiceId' is missing • Invalid column name 'PatientName' • Failed to convert parameter value from String to DateTime • BadRequest		• Review API request format and required parameters • Validate JSON payload structure • Check SQL syntax and verify column/table names • Ensure parameter types match expected schema • For login failures, contact practice to enable integration
401	Invalid Credentials • Wrong API subscription key • Incorrect environment	• Subscription Key Invalid • Subscription Key Not Found		• Verify subscription key matches environment • Check you're using correct environment (Stage vs Production) • Contact support if issues persist
403	Access Restrictions • IP address not allowlisted • Non-authoritative practice • Exceeded API quotas	• Caller Ip Not Allowed		• Contact support for IP allowlisting • Re-fetch practice Halo GUID if non-authoritative
404	Invalid Endpoints • Malformed API URLs • Incorrect endpoint paths	• Operation Not Found • Invalid URI structure		• Review API endpoint URLs • Check API reference • Verify HTTP method (GET/POST)
413	Response Size Limits • Query results exceed 8MB limit • Large dataset returned	• Query Results Too Large • Immediate query results beyond message size limit (8mb)		• Reduce query scope (add WHERE clauses) • Use pagination for large datasets • Switch to async queries • Consider breaking into smaller queries
429	Rate Limiting • Too many requests per time window	• Rate Limit Exceeded		• Check Retry-After header for recommended wait time • Implement request throttling • Add delays between requests • Contact support to discuss higher limits • Use exponential backoff

5xx server errors

5xx errors indicate server-side issues that are typically temporary. These are often infrastructure-related and usually resolve automatically.

Code	Common Causes	Examples	Recommended Actions
500	Server-Side Issues • Internal processing errors	• Internal Server Error	• Apply exponential backoff • If issue persists: Contact support • Monitor for resolution • Avoid overwhelming with retries
503	Service Unavailable • Practice server is offline before the query is attempted	• Site could not be contacted • Network connectivity failures	• Apply backoff strategy • Check for maintenance announcements • Contact support if prolonged
504	Timeout Issues • Long-running queries (>30 seconds) • Practice server offline after the query is attempted • Network timeouts	• Query took more than 30 seconds to return a result • Site is currently unreachable • Site is offline	• For query timeouts: Optimize SQL queries, use async queries for complex operations • For connectivity: Apply backoff, contact support if persistent • Monitor practice connectivity status via siteStatus