Error Handling and Retry Patterns

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request.",
    "details": [
      { "field": "transcript", "message": "transcript (or shorthand_notes) is required" },
      { "field": "specialty", "message": "specialty (or provider_type) is required" }
    ]
  }
}

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      // Non-retryable client errors (4xx): return immediately
      if (response.status >= 400 && response.status < 500) {
        return response;
      }

      // Success: return
      if (response.ok) {
        return response;
      }

      // Retryable errors (5xx): backoff and retry
      if (attempt < maxRetries) {
        const baseDelay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        const jitter = Math.random() * 1000;
        await new Promise(resolve => setTimeout(resolve, baseDelay + jitter));
        continue;
      }

      return response; // Max retries exhausted
    } catch (error) {
      // Network errors: retry
      if (attempt < maxRetries) {
        const baseDelay = Math.pow(2, attempt) * 1000;
        const jitter = Math.random() * 1000;
        await new Promise(resolve => setTimeout(resolve, baseDelay + jitter));
        continue;
      }
      throw error;
    }
  }
}

// Usage
const response = await fetchWithRetry(
  "https://api.soapnoteapi.com/v1/note",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      transcript: "Patient presents with...",
      specialty: "nurse_practitioner",
    }),
  }
);

import time
import random
import requests

def fetch_with_retry(url, method="POST", headers=None, json=None, max_retries=3):
    for attempt in range(max_retries + 1):
        try:
            response = requests.request(method, url, headers=headers, json=json, timeout=30)

            # Non-retryable client errors (4xx)
            if 400 <= response.status_code < 500:
                return response

            # Success
            if response.ok:
                return response

            # Retryable (5xx): backoff
            if attempt < max_retries:
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
                continue

            return response

        except requests.exceptions.RequestException:
            if attempt < max_retries:
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
                continue
            raise

# Usage
response = fetch_with_retry(
    "https://api.soapnoteapi.com/v1/note",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "transcript": "Patient presents with...",
        "specialty": "nurse_practitioner",
    },
)

const response = await fetch("https://api.soapnoteapi.com/v1/note", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ specialty: "nurse_practitioner" }), // Missing transcript
});

if (!response.ok) {
  const error = await response.json();

  if (error.error.code === "VALIDATION_ERROR") {
    // Show specific field errors to the developer / log them
    for (const detail of error.error.details || []) {
      console.error(`Field "${detail.field}": ${detail.message}`);
    }
    // Output: Field "transcript": transcript (or shorthand_notes) is required
  }
}

class CircuitBreaker {
  constructor(failureThreshold = 5, resetTimeMs = 30000) {
    this.failures = 0;
    this.threshold = failureThreshold;
    this.resetTime = resetTimeMs;
    this.state = "closed"; // closed = normal, open = failing, half-open = testing
    this.openedAt = null;
  }

  async execute(fn) {
    if (this.state === "open") {
      // Check if reset time has elapsed
      if (Date.now() - this.openedAt > this.resetTime) {
        this.state = "half-open";
      } else {
        throw new Error("Circuit breaker is open. SOAPNoteAPI may be experiencing issues.");
      }
    }

    try {
      const result = await fn();
      // Success: reset failures
      this.failures = 0;
      this.state = "closed";
      return result;
    } catch (error) {
      this.failures++;
      if (this.failures >= this.threshold) {
        this.state = "open";
        this.openedAt = Date.now();
      }
      throw error;
    }
  }
}

// Usage
const breaker = new CircuitBreaker(5, 30000);

try {
  const note = await breaker.execute(() =>
    fetchWithRetry("https://api.soapnoteapi.com/v1/note", requestOptions)
  );
} catch (error) {
  // Circuit is open: show fallback UI
  showMessage("Note generation is temporarily unavailable. Your transcript has been saved and will be processed when the service recovers.");
}