Error handling and retries

Error Handling with tryCatch

The R SDK uses R’s condition system for error handling. Use tryCatch to handle specific error types:

library(omophub)

client <- OMOPHubClient$new(api_key = "oh_xxx")

tryCatch(
  {
    concept <- client$concepts$get(999999999)
  },
  omophub_not_found = function(e) {
    cat(sprintf("Not found: %s\n", conditionMessage(e)))
  },
  omophub_auth_error = function(e) {
    cat(sprintf("Auth failed: %s\n", e$error_code))
  },
  omophub_forbidden_error = function(e) {
    cat("API key is valid but not permitted for this resource\n")
  },
  omophub_rate_limit_error = function(e) {
    cat(sprintf("Rate limited. Retry after %ds\n", e$retry_after %||% 5))
  },
  omophub_api_error = function(e) {
    cat(sprintf("API error %d: %s\n", e$status_code, conditionMessage(e)))
  }
)

Error Types

The SDK defines the following error conditions:

omophub_error              # Base error for all SDK errors
├── omophub_api_error      # API returned an error response
│   ├── omophub_validation_error # 400 - Invalid request parameters
│   ├── omophub_auth_error       # 401 - Invalid or missing API key
│   ├── omophub_forbidden_error  # 403 - Valid key, but not permitted
│   ├── omophub_not_found        # 404 - Resource not found
│   ├── omophub_rate_limit_error # 429 - Too many requests
│   └── omophub_server_error     # 500+ - Server-side error
└── omophub_connection_error     # Network connectivity issues

omophub_auth_error is also raised whenever the server reports invalid_api_key or missing_api_key, whatever the status. A 403 means the key was accepted but lacks access (for example, a restricted vocabulary), so it has its own class rather than being reported as an invalid key. Input the SDK rejects before sending a request (a non-integer concept_id, an empty query) raises omophub_validation_error too, but without omophub_api_error, since no request was made.

Every HTTP condition also keeps httr2’s classes (httr2_http_404, httr2_http, and httr2_failure for network errors) and the raw response in e$resp. Handlers written against httr2 conditions keep working.

Error Properties

API errors (omophub_api_error and its subclasses) include:

tryCatch(
  {
    concept <- client$concepts$get(999999999)
  },
  omophub_api_error = function(e) {
    print(conditionMessage(e)) # Human-readable error message
    print(e$status_code)       # HTTP status code
    print(e$error_code)        # Server error code, e.g. "not_found"
    print(e$details)           # Server-provided details, if any
    print(e$request_id)        # Request ID for debugging
    print(e$endpoint)          # Endpoint that failed
  }
)

omophub_rate_limit_error also has e$retry_after (seconds, or NULL if the server did not send Retry-After).

Rate Limiting

Handle rate limits with retry logic:

tryCatch(
  {
    results <- client$search$basic("diabetes")
  },
  omophub_rate_limit_error = function(e) {
    cat(sprintf("Rate limited. Retry after %d seconds\n", e$retry_after %||% 5))
    Sys.sleep(e$retry_after %||% 5)
    # Retry the request
    results <- client$search$basic("diabetes")
  }
)

The SDK automatically retries failed requests up to max_retries times (default: 3) with exponential backoff. You typically don’t need to handle transient errors manually.

Connection Errors

Handle network issues:

tryCatch(
  {
    concept <- client$concepts$get(201826)
  },
  omophub_connection_error = function(e) {
    cat(sprintf("Network error: %s\n", conditionMessage(e)))
    # Implement your retry logic or fallback
  }
)

Best Practices

Catch Specific Errors First

tryCatch(
  {
    concept <- client$concepts$get(concept_id)
  },
  omophub_not_found = function(e) {
    # Handle missing concept
    concept <- NULL
  },
  omophub_rate_limit_error = function(e) {
    # Wait and retry
    Sys.sleep(e$retry_after %||% 5)
  },
  omophub_api_error = function(e) {
    # Log and handle other API errors
    warning(sprintf("API error: %s", conditionMessage(e)))
    stop(e)
  }
)

Use withCallingHandlers for Logging

withCallingHandlers(
  {
    results <- client$search$basic("diabetes")
  },
  omophub_api_error = function(e) {
    # Log but don't handle - let it propagate
    message(sprintf("API call failed: %s", conditionMessage(e)))
  }
)

Wrap in a Safe Function

Create a helper function for common error handling:

safe_get_concept <- function(client, concept_id) {
  tryCatch(
    {
      client$concepts$get(concept_id)
    },
    omophub_not_found = function(e) {
      NULL
    },
    omophub_api_error = function(e) {
      warning(sprintf("Failed to get concept %d: %s", concept_id, conditionMessage(e)))
      NULL
    }
  )
}

# Usage
concept <- safe_get_concept(client, 201826)
if (!is.null(concept)) {
  print(concept$concept_name)
}

Python SDK

Node.js / TypeScript SDK

R SDK

Error Handling with tryCatch

Error Types

Error Properties

Rate Limiting

Connection Errors

Best Practices

Catch Specific Errors First

Use withCallingHandlers for Logging

Wrap in a Safe Function

​Error Handling with tryCatch

​Error Types

​Error Properties

​Rate Limiting

​Connection Errors

​Best Practices

​Catch Specific Errors First

​Use withCallingHandlers for Logging

​Wrap in a Safe Function

Error Handling with tryCatch

Error Types

Error Properties

Rate Limiting

Connection Errors

Best Practices

Catch Specific Errors First

Use withCallingHandlers for Logging

Wrap in a Safe Function