Vonage HTTP Client for Python

1.5.1 · active · verified Thu Apr 16

The `vonage-http-client` is a foundational Python HTTP client library for interacting with Vonage APIs. It provides low-level request building and authentication mechanisms, supporting API key/secret and JWT-based authentication. While primarily an internal dependency of the higher-level `vonage` Python SDK, it can be used directly for specific API interactions. The current version is 1.5.1, and it has a relatively stable release cadence, with updates typically coinciding with major SDK changes or specific HTTP client enhancements.

Common errors

```
from vonage_http_client import Client
ModuleNotFoundError: No module named 'vonage_http_client'
```
cause The `vonage-http-client` library is not installed in your Python environment.

fix Run `pip install vonage-http-client` to install the library.
```
vonage_http_client.exceptions.VonageServerException: Unauthorized
```
cause The Vonage API key and/or secret provided are invalid, missing, or do not have the necessary permissions for the requested operation.

fix Verify your `VONAGE_API_KEY` and `VONAGE_API_SECRET` environment variables or parameters passed to `Client()`. Ensure they are correct and active in your Vonage account, and have the appropriate permissions.
```
requests.exceptions.ConnectionError: ('Connection aborted.', RemoteDisconnected('Remote end closed connection without response'))
```
cause This typically indicates a network issue, an incorrect `base_url`, or a misconfigured proxy preventing the client from reaching the Vonage API servers.

fix Check your internet connection, verify the `base_url` provided to the `Client` constructor is correct (e.g., `https://api.nexmo.com`), and inspect any proxy settings that might be interfering.

Warnings

gotcha Users often mistake `vonage-http-client` for the primary Vonage Python SDK. While it provides low-level access, the `vonage` package (`pip install vonage`) offers a much richer, higher-level interface to Vonage APIs, handling endpoint specifics, data serialization, and common use cases.
Fix: For most application development, use `pip install vonage` and import from `vonage` instead of `vonage_http_client`.
gotcha When using `vonage-http-client` directly, you are responsible for constructing the full API endpoint path (e.g., `/account/balance` for `https://api.nexmo.com/account/balance`) and managing request body/query parameters manually, unlike the higher-level SDK which abstracts these details.
Fix: Refer to the specific Vonage API documentation for the exact paths and parameters required for each endpoint. Alternatively, use the `vonage` SDK for simplified API calls.
gotcha Authentication failures (e.g., HTTP 401 Unauthorized) are common when using the client directly if API key/secret or JWT details are incorrect, expired, or if the API key lacks necessary permissions for the requested endpoint.
Fix: Double-check your API key and secret, ensure they are active in your Vonage account, and verify that the associated API key has the required permissions for the API endpoint you are calling.

Install

pip install vonage-http-client Install stable version

Imports

Client
wrong:
```
from vonage_http_client.client import Client
```
correct:
```
from vonage_http_client import Client
```
The Client class is exposed directly at the top level of the package.

Quickstart

This quickstart demonstrates how to instantiate the `vonage-http-client` with API key/secret and make a basic GET request to a Vonage API endpoint. Remember to set `VONAGE_API_KEY` and `VONAGE_API_SECRET` environment variables. For more complex interactions, the full `vonage` Python SDK is generally preferred as it handles endpoint paths and response parsing automatically.

import os
from vonage_http_client import Client
from vonage_http_client.exceptions import VonageServerException

# NOTE: For most users, the higher-level 'vonage' SDK (pip install vonage)
# is recommended for easier API interaction.

# Retrieve API key and secret from environment variables
API_KEY = os.environ.get('VONAGE_API_KEY', '')
API_SECRET = os.environ.get('VONAGE_API_SECRET', '')

if not API_KEY or not API_SECRET:
    print("Warning: Please set VONAGE_API_KEY and VONAGE_API_SECRET environment variables.")
    print("Skipping quickstart as authentication is required.")
else:
    try:
        # Instantiate the HTTP client with your Vonage API credentials
        client = Client(
            api_key=API_KEY,
            api_secret=API_SECRET,
            # For demonstration, using a common Vonage API base URL.
            # Specific API paths (e.g., /account/balance) need to be appended manually.
            base_url="https://api.nexmo.com"
        )

        # Example: Make a GET request to a Vonage API endpoint.
        # This will likely require valid credentials and specific endpoint access.
        # A common endpoint is '/account/balance'.
        print("Attempting to fetch account balance...")
        response = client.get('/account/balance')

        print(f"Status Code: {response.status_code}")
        print(f"Response Body: {response.json()}")

    except VonageServerException as e:
        print(f"Vonage API error: {e.status_code} - {e.reason} - {e.error_response}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →