# Error Handling

> Medical Device processing is synchronous — all errors are returned directly in the API response. There are no async error callbacks for this module.


## Unsupported file type (HTTP 201, success: false)

```json
{
  "success": false,
  "message": "Unsupported file type \"device.xyz\" for medical module. Supported types: JPEG, PNG, GIF, WEBP, PDF."
}
```

When `success` is `false`, the `data` field is absent. The `message` field is a top-level string.

## Extraction failure

When the file is accepted but extraction fails (e.g. the AI cannot read the device display), the top-level response has `success: true` but the individual extraction result carries `success: false` and an `error` field.

```json
{
  "success": true,
  "data": {
    "type": "medical",
    "status": "extracted",
    "extractions": [
      {
        "fileName": "blurry-device.png",
        "result": {
          "status": "error",
          "data": {
            "success": false,
            "error": "Could not detect a recognizable medical device in the image"
          },
          "message": "Medical data extracted successfully from PNG file"
        }
      }
    ],
    "filesCount": 1,
    "message": "1 medical file(s) processed successfully"
  }
}
```

Check `extractions[].result.data.success` to determine whether each individual file was extracted successfully.

## API timeout

When the extraction backend does not respond within 30 seconds, the result for that file is:

```json
{
  "success": true,
  "data": {
    "type": "medical",
    "status": "extracted",
    "extractions": [
      {
        "fileName": "device.png",
        "result": {
          "status": "error",
          "data": null,
          "message": "API request timeout after 30 seconds",
          "error": "timeout"
        }
      }
    ],
    "filesCount": 1,
    "message": "1 medical file(s) processed successfully"
  }
}
```

Retry the upload with the same file if this occurs — transient timeouts are uncommon.

## Network or unknown error

When the extraction request fails due to a network error or unexpected exception, the result follows the same shape as a timeout but with a descriptive `error` message:

```json
{
  "status": "error",
  "data": null,
  "message": "Failed to extract medical data: <error detail>",
  "error": "<error detail>"
}
```

## Unauthorized (HTTP 401)

```json
{
  "success": false,
  "statusCode": 401,
  "path": "/api/master?module=medical",
  "timestamp": "2026-04-02T08:26:13.716Z",
  "message": "Invalid API token format",
  "error": "Unauthorized"
}
```

Three distinct `message` values are possible:

| Message | Cause |
|  --- | --- |
| `"API token required"` | `Authorization` header is missing entirely |
| `"Invalid API token format"` | Header present but token doesn't match the expected format |
| `"Invalid API token"` | Token is correctly formatted but not found or account is inactive |


## Troubleshooting

| Symptom | Likely cause | Fix |
|  --- | --- | --- |
| `401` — `"API token required"` | `Authorization` header missing | Add `Authorization: Bearer <token>` to every request |
| `401` — `"Invalid API token format"` | Token format wrong | Check for extra spaces, quotes, or missing `Bearer` prefix |
| `401` — `"Invalid API token"` | Token not recognised or account inactive | Verify the token in the Integration page; regenerate if needed |
| Unsupported file type response | File format not accepted | Convert to JPEG, PNG, GIF, WEBP, or PDF and retry |
| `extractions[].result.data.success` is `false` | Device not detected or image quality too low | Check the `error` field; improve lighting, angle, and focus |
| `error: "timeout"` in extraction result | Backend did not respond within 30 seconds | Retry the upload; if persistent, contact [support@jonda.health](mailto:support@jonda.health) |
| Low confidence score (`< 0.7`) | Poor image quality or unusual device layout | Retake the photo — clear, well-lit, straight-on |