{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"API Errors","description":"API documentation for integrating with NovaMed - healthcare partner integration platform","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-errors","__idx":0},"children":["API Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Understand error responses and handle them properly in your integration."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-response-format","__idx":1},"children":["Error Response Format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All errors follow a consistent format:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Human-readable error message\",\n    \"details\": {}\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-fields","__idx":2},"children":["Error Fields"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Always ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," for errors"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable error description"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.details"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Additional error information (optional)"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"http-status-codes","__idx":3},"children":["HTTP Status Codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following table describes all the possible HTTP error codes:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Name"},"children":["Name"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OK"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request succeeded"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Created"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource created successfully"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bad Request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid request parameters or validation error"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unauthorized"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Missing or invalid API key"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not Found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resource not found"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5XX"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Server Error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An error occurred on the NovaMed API"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-error-scenarios","__idx":4},"children":["Common Error Scenarios"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"400-bad-request","__idx":5},"children":["400 Bad Request"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returned when request validation fails:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Clinic ID must be a valid UUID.\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Common causes:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Missing required fields"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invalid field formats (UUID, email, etc.)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invalid clinic ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invalid practitioner or patient ID"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example - Clinic not found:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Clinic not found\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"401-unauthorized","__idx":6},"children":["401 Unauthorized"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returned when authentication fails:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Unauthorized. This can happen if the access token is invalid, expired or has been revoked\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Solutions:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header is present"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Check that the API key is valid"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure you're using the correct environment"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"404-not-found","__idx":7},"children":["404 Not Found"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Returned when a resource doesn't exist:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Resource not found\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Common causes:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Invalid resource ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Resource was deleted"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Wrong environment"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"refill-specific-errors","__idx":8},"children":["Refill-Specific Errors"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Medication request not found\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Refills are not possible for pending medication requests\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"message\": \"Refill request already exists\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling-best-practices","__idx":9},"children":["Error Handling Best Practices"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-check-response-status","__idx":10},"children":["1. Check Response Status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}," field in responses:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nresponse = requests.post(url, headers=headers, json=data)\nresult = response.json()\n\nif result.get('success'):\n    # Handle success\n    data = result.get('data')\nelse:\n    # Handle error\n    error_message = result.get('error', {}).get('message')\n    print(f\"Error: {error_message}\")\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-handle-different-error-types","__idx":11},"children":["2. Handle Different Error Types"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"def handle_api_error(response):\n    result = response.json()\n    \n    if response.status_code == 400:\n        # Validation error - check your request\n        raise ValidationError(result['error']['message'])\n    \n    elif response.status_code == 401:\n        # Authentication error - check API key\n        raise AuthenticationError(\"Invalid API key\")\n    \n    elif response.status_code == 404:\n        # Resource not found\n        raise NotFoundError(result['error']['message'])\n    \n    elif response.status_code >= 500:\n        # Server error - retry with backoff\n        raise ServerError(\"NovaMed API error, please retry\")\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-implement-retry-logic","__idx":12},"children":["3. Implement Retry Logic"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For server errors (5XX), implement retry with exponential backoff:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import time\n\ndef retry_with_backoff(func, max_retries=3):\n    for attempt in range(max_retries):\n        try:\n            return func()\n        except ServerError as e:\n            if attempt == max_retries - 1:\n                raise\n            \n            wait_time = 2 ** attempt  # 1s, 2s, 4s\n            print(f\"Retrying in {wait_time}s...\")\n            time.sleep(wait_time)\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-log-errors-for-debugging","__idx":13},"children":["4. Log Errors for Debugging"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import logging\n\nlogger = logging.getLogger(__name__)\n\ndef make_api_request(endpoint, data):\n    try:\n        response = requests.post(endpoint, json=data, headers=headers)\n        result = response.json()\n        \n        if not result.get('success'):\n            logger.error(f\"API Error: {result.get('error')}\")\n            logger.error(f\"Request Data: {data}\")\n        \n        return result\n    \n    except Exception as e:\n        logger.exception(f\"Request failed: {e}\")\n        raise\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency","__idx":14},"children":["Idempotency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For operations that create resources, ensure idempotency by:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Using unique identifiers"]},": Generate unique IDs on your side before creating resources"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Checking for existing resources"]},": Before creating, check if a resource already exists"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handling duplicates gracefully"]},": If a resource already exists, return the existing one"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-preventing-duplicate-refill-requests","__idx":15},"children":["Example: Preventing Duplicate Refill Requests"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"def request_refill(medication_request_id):\n    \"\"\"\n    Request a refill, handling the case where one already exists.\n    \"\"\"\n    response = requests.post(\n        f\"{BASE_URL}/api/external/refill-request\",\n        headers=headers,\n        json={\"medication_request_id\": medication_request_id}\n    )\n    \n    result = response.json()\n    \n    if result.get('success'):\n        return result['data']\n    \n    # Check if refill already exists\n    if \"already exists\" in result.get('error', {}).get('message', ''):\n        # Refill was already requested - this is OK\n        return {\"status\": \"already_requested\"}\n    \n    # Other error\n    raise RefillError(result['error']['message'])\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling-examples","__idx":16},"children":["Error Handling Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"python","__idx":17},"children":["Python"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import requests\n\nBASE_URL = \"https://novamed-feapidev.nimbushealthcaretest.com\"\n\ndef create_practitioner(practitioner_data):\n    \"\"\"Create a practitioner with proper error handling.\"\"\"\n    \n    response = requests.post(\n        f\"{BASE_URL}/api/external/practitioner\",\n        headers={\n            \"x-api-key\": API_KEY,\n            \"Content-Type\": \"application/json\",\n            \"Accept\": \"application/json\"\n        },\n        json=practitioner_data\n    )\n    \n    result = response.json()\n    \n    if result.get('success'):\n        return result['data']\n    \n    error_message = result.get('error', {}).get('message', 'Unknown error')\n    \n    if response.status_code == 400:\n        raise ValueError(f\"Validation error: {error_message}\")\n    elif response.status_code == 401:\n        raise PermissionError(\"Invalid API key\")\n    elif response.status_code == 404:\n        raise LookupError(error_message)\n    else:\n        raise Exception(f\"API error: {error_message}\")\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"nodejs","__idx":18},"children":["Node.js"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const axios = require('axios');\n\nconst BASE_URL = 'https://novamed-feapidev.nimbushealthcaretest.com';\n\nasync function createPractitioner(practitionerData) {\n  try {\n    const response = await axios.post(\n      `${BASE_URL}/api/external/practitioner`,\n      practitionerData,\n      {\n        headers: {\n          'x-api-key': process.env.NOVAMED_API_KEY,\n          'Content-Type': 'application/json',\n          'Accept': 'application/json'\n        }\n      }\n    );\n    \n    if (response.data.success) {\n      return response.data.data;\n    }\n    \n    throw new Error(response.data.error?.message || 'Unknown error');\n    \n  } catch (error) {\n    if (error.response) {\n      const status = error.response.status;\n      const message = error.response.data?.error?.message;\n      \n      if (status === 400) {\n        throw new Error(`Validation error: ${message}`);\n      } else if (status === 401) {\n        throw new Error('Invalid API key');\n      } else if (status === 404) {\n        throw new Error(`Not found: ${message}`);\n      }\n    }\n    \n    throw error;\n  }\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":19},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/authentication"},"children":["Learn about authentication"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/webhooks"},"children":["Set up webhooks"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/api-reference"},"children":["Read the API reference"]}]}]}]},"headings":[{"value":"API Errors","id":"api-errors","depth":1},{"value":"Error Response Format","id":"error-response-format","depth":2},{"value":"Error Fields","id":"error-fields","depth":3},{"value":"HTTP Status Codes","id":"http-status-codes","depth":2},{"value":"Common Error Scenarios","id":"common-error-scenarios","depth":2},{"value":"400 Bad Request","id":"400-bad-request","depth":3},{"value":"401 Unauthorized","id":"401-unauthorized","depth":3},{"value":"404 Not Found","id":"404-not-found","depth":3},{"value":"Refill-Specific Errors","id":"refill-specific-errors","depth":3},{"value":"Error Handling Best Practices","id":"error-handling-best-practices","depth":2},{"value":"1. Check Response Status","id":"1-check-response-status","depth":3},{"value":"2. Handle Different Error Types","id":"2-handle-different-error-types","depth":3},{"value":"3. Implement Retry Logic","id":"3-implement-retry-logic","depth":3},{"value":"4. Log Errors for Debugging","id":"4-log-errors-for-debugging","depth":3},{"value":"Idempotency","id":"idempotency","depth":2},{"value":"Example: Preventing Duplicate Refill Requests","id":"example-preventing-duplicate-refill-requests","depth":3},{"value":"Error Handling Examples","id":"error-handling-examples","depth":2},{"value":"Python","id":"python","depth":3},{"value":"Node.js","id":"nodejs","depth":3},{"value":"Next Steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Errors & Idempotency","description":"Handle API errors and ensure reliable operations","seo":{"title":"API Errors"}},"lastModified":"2025-12-19T22:59:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/errors-idempotency","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}