Handling Dolva API Errors: Auth, Validation, and More

Dolva returns standard HTTP status codes to indicate success or failure. Building robust error handling into your integration ensures that failures degrade gracefully rather than crashing your application.

HTTP Status Codes

Status	Meaning	Common Cause
`200 OK`	Request succeeded	—
`401 Unauthorized`	Authentication failed	Missing or invalid Bearer token
`403 Forbidden`	Access denied	Token valid but lacks required permissions
`422 Unprocessable Entity`	Validation error	Missing `audio` field or invalid file format
`500 Internal Server Error`	Server error	Transient issue — retry with backoff

Validation Errors (422)

When your request is missing required fields or contains invalid data, Dolva returns a 422 response with a detailed error body:

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "audio"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Each item in detail describes one validation failure:

loc — where the error occurred (e.g., ["body", "audio"] means the audio field in the request body is the problem)
msg — a human-readable description of the error
type — a machine-readable error type string

Common 422 causes:

The audio field is missing from your multipart/form-data request
The file is empty or corrupt
The content type is not recognized as audio

Handling Errors in Code

import requests
import os
import time

def analyze_audio(path, endpoint="cognitive", retries=3):
    token = os.environ["DOLVA_API_TOKEN"]
    url = f"https://api.dolva.ai/v1/analyze/{endpoint}"

    for attempt in range(retries):
        with open(path, "rb") as f:
            resp = requests.post(
                url,
                headers={"Authorization": f"Bearer {token}"},
                files={"audio": f}
            )

        if resp.status_code == 200:
            return resp.json()
        elif resp.status_code == 401:
            raise Exception("Invalid API token. Check your DOLVA_API_TOKEN.")
        elif resp.status_code == 422:
            raise Exception(f"Validation error: {resp.json()}")
        elif resp.status_code >= 500:
            if attempt < retries - 1:
                time.sleep(2 ** attempt)  # exponential backoff
                continue
            raise Exception(f"Server error after {retries} attempts: {resp.status_code}")
        else:
            raise Exception(f"Unexpected error {resp.status_code}: {resp.text}")

async function analyzeAudio(filePath, endpoint = "cognitive", retries = 3) {
  const { default: fetch } = await import("node-fetch");
  const { default: FormData } = await import("form-data");
  const fs = await import("fs");

  const token = process.env.DOLVA_API_TOKEN;
  const url = `https://api.dolva.ai/v1/analyze/${endpoint}`;

  for (let attempt = 0; attempt < retries; attempt++) {
    const form = new FormData();
    form.append("audio", fs.createReadStream(filePath));

    const response = await fetch(url, {
      method: "POST",
      headers: { Authorization: `Bearer ${token}`, ...form.getHeaders() },
      body: form,
    });

    if (response.ok) return response.json();

    const body = await response.json().catch(() => ({}));

    if (response.status === 401) throw new Error("Invalid API token.");
    if (response.status === 422) throw new Error(`Validation error: ${JSON.stringify(body)}`);
    if (response.status >= 500 && attempt < retries - 1) {
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
      continue;
    }
    throw new Error(`Request failed with status ${response.status}`);
  }
}

Retrying on Server Errors

For 5xx errors, implement exponential backoff: wait 1s before the first retry, 2s before the second, 4s before the third, and so on. Most transient server errors resolve within a few seconds.

Do NOT retry 401 or 422 errors — these indicate problems with your request that won’t resolve on their own. Fix the underlying issue before retrying.

Checking API Health

Before sending large batches of requests, you can verify that the Dolva API is reachable by calling the health endpoint (no authentication required):

curl

curl https://api.dolva.ai/health

A 200 OK response confirms the API is up. See the Health endpoint reference for details.

Authentication

Troubleshoot 401 errors and token setup.

Health Endpoint

Check API availability before batch operations.

Get Started

Core Concepts

Guides

Handling Dolva API Errors: Auth, Validation, and More

HTTP Status Codes

Validation Errors (422)

Handling Errors in Code

Retrying on Server Errors

Checking API Health

Authentication

Health Endpoint

​HTTP Status Codes

​Validation Errors (422)

​Handling Errors in Code

​Retrying on Server Errors

​Checking API Health

Authentication

Health Endpoint

HTTP Status Codes

Validation Errors (422)

Handling Errors in Code

Retrying on Server Errors

Checking API Health