Technical troubleshooting

Introduction

Even well-documented and robust APIs can pose unexpected challenges during integration. From authentication issues to handling rate limits and parsing complex responses, these common hurdles can slow down development and complicate production deployments. The following troubleshooting tips aim to help you identify common error patterns, understand their root causes, and apply practical solutions, allowing you to build reliable applications on top of the API.

Most common REST API issues

This section describes common issues you may encounter when using the API and provides guidance on how to resolve them. If you continue to experience problems after trying these solutions, consider reaching out to our support team.

Authentication errors

Symptoms:

• Receiving an HTTP 401 (Unauthorized) or 403 (Forbidden) response.
• Responses indicating "Invalid token" or "Expired token."

Possible causes:

• Omitted or malformed Authorization header.
• Expired or invalid access token.
• Incorrect credentials or field names in form data when calling the /login endpoint.

Solutions:

• Ensure you have included the Bearer access_token in the Authorization header for protected endpoints.
• The JSON Web Tokens (JWTs) generated by the API have a limited lifespan. If the token is expired, request a new token via /login using valid credentials.
• Double-check that your username and password are correct and have not been changed or revoked.

Invalid or malformed request payloads

Symptoms:

• Receiving an HTTP 400 (Bad Request) error.
• Error messages related to malformed JSON or missing required fields.

Possible causes:

• JSON payload not properly formatted (e.g., missing braces or commas).
• Required parameters not included.
• Non-JSON content type in request headers.

Solutions:

• Use a JSON validator before making the request to check the JSON syntax.
• Refer to the endpoint documentation to ensure all mandatory fields (e.g., media, bodySite) are present.
• Include Content-Type: application/json in the request header for the clinical services.

Image upload and quality issues

Symptoms:

• Receiving an HTTP 400 or 422 (Unprocessable Entity) responses indicating invalid image data or format.
• Inconsistent or unexpected results from /diagnosis-support or /severity-assessment.

Possible causes:

• Unsupported image formats (only Base64-encoded images are supported).
• The image file is corrupted or incomplete.
• Poor image quality resulting in low confidence from the clinical computer vision models.
• Non-dermatological images submitted to services expecting dermatological content.

Solutions:

• Confirm that the image is encoded in Base64 and uses a supported file format, such as JPEG or PNG.
• Verify that the image file is not corrupted and the image data is properly encoded.
• Use higher-resolution images with no blurriness, good lighting and focus.
• Ensure the image is dermatological in nature. Non-dermatological images may cause the device’s domain model to return highly uncertain results.

Unclear or unexpected results

Symptoms:

• Unexpected distribution of possible ICD-11 categories, predicted visual signs or masks, or scores from automatic scoring systems.
• Results that differ significantly from clinical expectation.

Possible causes:

• Input image may not clearly show the relevant skin condition.
• The model's confidence in identifying certain conditions may be low due to ambiguous images (e.g., images showing more than one skin disorder).
• Clinical result generation relies on multiple models; if upstream models (e.g., domain or quality) produce uncertain outputs, downstream clinical interpretations may be affected.

Solutions:

• Provide images that clearly show the affected skin area, preferably with proper lighting and focus.
• Review the documentation to confirm that the submitted condition is within the supported set of conditions for the /diagnosis-support or /severity-assessment endpoints.
• If possible, provide additional image angles or improved capture conditions to help the model perform more accurately.

Network and performance issues

Symptoms:

• API is not reachable.
• Slow response times or request timeouts.
• Intermittent connectivity or server unavailability errors (e.g., HTTP 502 or 503).

Possible causes:

• DNS or firewall blocks.
• Unexpected errors in server-side logic.
• Temporary server downtime or maintenance.
• High server load.
• Poor network connection on the client side.
• Large image sizes causing increased processing time.

Solutions:

• Check the API’s status page (if available) or contact support to see if there is ongoing maintenance or a known service disruption.
• Check if your network or firewall settings allow outbound requests to the API's web domain.
• If encountering temporary server issues, wait a few minutes before retrying.
• Reduce image file size (without compromising clarity) to improve processing times. Performance will remain unaffected, as our computer vision models are designed to work with medium-quality images.
• Ensure that your client has a stable internet connection and consider adjusting request timeouts.

Rate limiting

Symptoms:

• Receiving HTTP 429 (Too Many Requests) responses.
• Sudden temporary inability to access protected endpoints even with valid authentication.

Possible causes:

• Exceeding the allowed request limit within a given time window.
• Rapidly sending multiple requests or performing bulk operations without proper pacing.

Solutions:

• Upon receiving a 429 error, wait the duration specified in the Retry-After header before sending another request. If this header is not present, wait a few seconds and retry the request.
• Whenever possible, schedule or batch requests to avoid bursting many within a short interval.
• Refer to the API’s stated rate limits and adjust your usage to remain within allowed quotas.
• Cache static or rarely changing information to minimize repeated API calls.

Incorrect URLs, endpoint deprecations or version incompatibilities

Symptoms:

• Receiving an HTTP 404 (Not Found) error.
• Unexpected errors after a recent API update or version release.
• Errors indicating that certain parameters or endpoints are not recognized.

Possible causes:

• Typographical errors in the URL.
• Using deprecated endpoints or parameters.
• Not following the most recent API documentation or version guidelines.

Solutions:

• Confirm that the base URL and/or path segments match the documentation exactly. Also, verify that you are using the correct HTTP verb (GET or POST).
• Verify you are using the latest endpoint URLs and data schemas for the request body.
• If endpoints have been deprecated, update your client application to use the recommended alternatives.
• Check the change logs or release notes for details on updated behaviors or data fields.

Need further assistance?

If the solutions above do not resolve your issue, please contact our technical support team at support@legit.health. Include the following details in your request:

• The endpoint you were using.
• Request and response details (e.g., timestamps, headers, payloads, and error messages).
• Steps to reproduce the issue.

This information helps us diagnose and resolve your issue more efficiently.