Skip to main content
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

StatusMeaningCommon Cause
200 OKRequest succeeded—
401 UnauthorizedAuthentication failedMissing or invalid Bearer token
403 ForbiddenAccess deniedToken valid but lacks required permissions
422 Unprocessable EntityValidation errorMissing audio field or invalid file format
500 Internal Server ErrorServer errorTransient 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}")

​
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.