scriptivox 0.1.0__py3-none-any.whl

scriptivox/_common.py

@@ -0,0 +1,293 @@
+"""Logic shared by the sync and async clients: retry rules, error mapping, filenames, file sources."""
+from __future__ import annotations
+
+import email.utils
+import io
+import json
+import os
+import platform
+import random
+import time
+import unicodedata
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Dict, Iterator, Mapping, NamedTuple, Optional, Union
+
+from ._error_codes import ERROR_CLASS_BY_CODE
+from ._exceptions import APIError, category_for_status
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.scriptivox.com"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_MAX_RETRIES = 2
+#: A Retry-After longer than this is not waited out automatically; the error is raised instead.
+MAX_RETRY_AFTER = 60.0
+DEFAULT_WAIT_TIMEOUT = 2 * 60 * 60.0
+DEFAULT_POLL_INTERVAL = 2.0
+DEFAULT_MAX_POLL_INTERVAL = 10.0
+#: Per socket operation during the file upload: no byte moving for this long ends that try.
+UPLOAD_IDLE_TIMEOUT = 120.0
+CHUNK = 1024 * 1024
+MAX_FILENAME = 255
+TRANSCRIPTION_OPTION_KEYS = ("language", "diarize", "speaker_count", "align", "webhook_url")
+
+
+class UploadProgress(NamedTuple):
+    """Passed to ``on_progress`` as the file's bytes are sent."""
+
+    loaded: int
+    total: int
+    #: 0–100.
+    percent: float
+
+
+FileInput = Union[str, "os.PathLike[str]", bytes, bytearray, memoryview, io.IOBase, Any]
+ProgressCallback = Callable[[UploadProgress], None]
+
+
+def normalize_base_url(url: str) -> str:
+    url = url.rstrip("/")
+    return url[: -len("/v1")] if url.endswith("/v1") else url
+
+
+def user_agent() -> str:
+    try:
+        import httpx
+
+        httpx_version = httpx.__version__
+    except Exception:  # pragma: no cover
+        httpx_version = "unknown"
+    return f"scriptivox-python/{__version__} python/{platform.python_version()} httpx/{httpx_version}"
+
+
+def parse_retry_after(value: Optional[str]) -> Optional[float]:
+    """Retry-After as seconds: delta-seconds or an HTTP date."""
+    if not value:
+        return None
+    value = value.strip()
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())
+
+
+def backoff(attempt: int) -> float:
+    """Exponential backoff with jitter: 0.5 s, 1 s, 2 s, … up to 8 s, ±25 %."""
+    return float(min(0.5 * 2.0**attempt, 8.0) * (0.75 + random.random() * 0.5))
+
+
+def error_from_response(status: int, text: str, headers: Mapping[str, str]) -> APIError:
+    """The typed error for an error answer. Handles a non-JSON body (e.g. an HTML 413 from the network layer)."""
+    lower = {k.lower(): v for k, v in headers.items()}
+    try:
+        parsed = json.loads(text) if text else None
+    except ValueError:
+        parsed = None
+    error = parsed.get("error") if isinstance(parsed, dict) and isinstance(parsed.get("error"), dict) else None
+    code = error.get("code") if error and isinstance(error.get("code"), str) else "UNKNOWN_ERROR"
+    snippet = " ".join(text.split())[:200]
+    message = error.get("message") if error and isinstance(error.get("message"), str) else f"HTTP {status}" + (f": {snippet}" if snippet else "")
+    request_id = (error.get("request_id") if error and isinstance(error.get("request_id"), str) else None) or lower.get("x-request-id")
+    retry_after = parse_retry_after(lower.get("retry-after"))
+    if retry_after is None and isinstance(parsed, dict) and isinstance(parsed.get("retry_after"), (int, float)):
+        retry_after = float(parsed["retry_after"])
+    cls = ERROR_CLASS_BY_CODE.get(code) or category_for_status(status)
+    return cls(
+        status=status,
+        code=code,
+        message=message,
+        request_id=request_id,
+        docs_url=error.get("docs_url") if error and isinstance(error.get("docs_url"), str) else None,
+        retry_after=retry_after,
+        error=error,
+        headers=lower,
+    )
+
+
+def retry_delay_for(err: APIError, idempotent: bool, attempt: int) -> Optional[float]:
+    """Whether an error answer is worth another try, and after how many seconds.
+
+    - 429 or 503 with Retry-After (rate limit, maintenance): refused before any work, so retried whatever
+      the method, after Retry-After (up to MAX_RETRY_AFTER). A 429 without Retry-After is the
+      jobs-in-progress cap: retrying at once cannot help.
+    - 409 IDEMPOTENCY_KEY_LOCKED: the first request with this key is still running; retry shortly.
+    - 408 and other 5xx: only when the request is safe to repeat.
+    """
+    ra = err.retry_after
+    if err.status in (429, 503):
+        if ra is not None:
+            return ra if ra <= MAX_RETRY_AFTER else None
+        if err.status == 429:
+            return None
+    if err.code == "IDEMPOTENCY_KEY_LOCKED":
+        return ra if ra is not None and ra <= MAX_RETRY_AFTER else backoff(attempt)
+    if idempotent and (err.status == 408 or err.status >= 500):
+        return ra if ra is not None and ra <= MAX_RETRY_AFTER else backoff(attempt)
+    return None
+
+
+def query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            value = value.replace(tzinfo=timezone.utc)
+        return str(value.astimezone(timezone.utc).isoformat()).replace("+00:00", "Z")
+    return str(value)
+
+
+def build_query(params: Mapping[str, Any]) -> Dict[str, str]:
+    return {k: query_value(v) for k, v in params.items() if v is not None}
+
+
+def safe_filename(name: str) -> str:
+    """The filename the API accepts: printable ASCII, no path separators, none of < > " ' `, at most
+    255 characters, with an extension. Accents are dropped (é → e), anything else becomes "_"."""
+    base = name.replace("\\", "/").rsplit("/", 1)[-1]
+    decomposed = unicodedata.normalize("NFKD", base)
+    stripped = "".join(c for c in decomposed if not unicodedata.combining(c))
+    safe = "".join(c if 0x20 <= ord(c) <= 0x7E and c not in '<>"\'`' else "_" for c in stripped).strip()
+    dot = safe.rfind(".")
+    if dot <= 0 or dot == len(safe) - 1:
+        raise ValueError(f'The filename "{name}" needs an extension such as .mp3 or .mp4: pass filename=.')
+    if len(safe) > MAX_FILENAME:
+        ext = safe[dot:]
+        safe = safe[: MAX_FILENAME - len(ext)] + ext
+    return safe
+
+
+@dataclass
+class FileSource:
+    name: Optional[str]
+    size: int
+    repeatable: bool
+    _open: Callable[[], Iterator[bytes]]
+    _used: bool = False
+
+    def chunks(self) -> Iterator[bytes]:
+        if not self.repeatable:
+            if self._used:
+                raise ValueError("A stream can only be uploaded once.")
+            self._used = True
+        return self._open()
+
+
+def resolve_source(file: Any, size: Optional[int] = None) -> FileSource:
+    """Any accepted input as a sized, (where possible) re-readable byte source."""
+    if isinstance(file, (str, os.PathLike)):
+        path = os.fspath(file)
+        if not os.path.isfile(path):
+            raise FileNotFoundError(f"{path} is not a file.")
+        file_size = os.path.getsize(path)
+
+        def read_path() -> Iterator[bytes]:
+            with open(path, "rb") as fh:
+                while True:
+                    chunk = fh.read(CHUNK)
+                    if not chunk:
+                        return
+                    yield chunk
+
+        return FileSource(os.path.basename(path), file_size, True, read_path)
+
+    if isinstance(file, (bytes, bytearray, memoryview)):
+        data = bytes(file)
+
+        def read_bytes() -> Iterator[bytes]:
+            for i in range(0, len(data), CHUNK):
+                yield data[i : i + CHUNK]
+
+        return FileSource(None, len(data), True, read_bytes)
+
+    if hasattr(file, "read"):
+        raw_name = getattr(file, "name", None)
+        name = os.path.basename(raw_name) if isinstance(raw_name, str) else None
+        seekable = bool(getattr(file, "seekable", lambda: False)())
+        start = file.tell() if seekable else 0
+        if size is None:
+            if not seekable:
+                raise ValueError("Uploading a non-seekable stream needs its byte length: pass size=.")
+            file.seek(0, io.SEEK_END)
+            size = file.tell() - start
+            file.seek(start)
+
+        def read_stream() -> Iterator[bytes]:
+            if seekable:
+                file.seek(start)
+            while True:
+                chunk = file.read(CHUNK)
+                if not chunk:
+                    return
+                if isinstance(chunk, str):
+                    raise TypeError("Open the file in binary mode ('rb').")
+                yield chunk
+
+        return FileSource(name, int(size), seekable, read_stream)
+
+    raise TypeError("file must be a path, bytes, or a binary file object.")
+
+
+def counted(source: FileSource, on_progress: Optional[ProgressCallback]) -> Iterator[bytes]:
+    """The source's chunks, checking the byte count and reporting progress."""
+    sent = 0
+    for chunk in source.chunks():
+        if sent + len(chunk) > source.size:
+            raise ValueError(f"The source has more bytes than the size given ({source.size}).")
+        yield chunk
+        sent += len(chunk)
+        if on_progress:
+            on_progress(UploadProgress(sent, source.size, round(sent / source.size * 100, 1) if source.size else 100.0))
+    if sent != source.size:
+        raise ValueError(f"The source ended after {sent} of {source.size} bytes.")
+    if source.size == 0 and on_progress:
+        on_progress(UploadProgress(0, 0, 100.0))
+
+
+def transcribe_body(
+    url: Optional[str],
+    upload_id: Optional[str],
+    options: Mapping[str, Any],
+) -> Dict[str, Any]:
+    body: Dict[str, Any] = {k: options[k] for k in TRANSCRIPTION_OPTION_KEYS if options.get(k) is not None}
+    if url is not None:
+        body["url"] = url
+    if upload_id is not None:
+        body["upload_id"] = upload_id
+    return body
+
+
+def check_one_source(url: Any, file: Any, upload_id: Any) -> None:
+    if sum(x is not None for x in (url, file, upload_id)) != 1:
+        raise TypeError("transcribe() needs exactly one of url=, file= or upload_id=.")
+
+
+def path_id(transcription_id: str) -> str:
+    if not isinstance(transcription_id, str) or not transcription_id:
+        raise TypeError("A transcription id is required.")
+    from urllib.parse import quote
+
+    return quote(transcription_id, safe="")
+
+
+def export_query(fmt: str, options: Mapping[str, Any]) -> Dict[str, str]:
+    if fmt == "json":
+        return {}
+    params: Dict[str, Any] = {"format": fmt}
+    for key, value in options.items():
+        if value is None:
+            continue
+        if key == "include_speakers" and isinstance(value, bool):
+            value = "true" if value else "false"
+        params[key] = value
+    return build_query(params)
+
+
+def monotonic() -> float:
+    return time.monotonic()

scriptivox/_error_codes.py

@@ -0,0 +1,190 @@
+# GENERATED by scripts/generate.py from openapi/openapi.json — do not edit by hand.
+# OpenAPI 1.0.0 · sha256 489f83bddaa9893f
+"""One exception class per API ``error.code``, and the codes a job can end with."""
+from __future__ import annotations
+
+from typing import Dict, Tuple, Type
+
+from ._exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    GoneError,
+    InternalServerError,
+    MethodNotAllowedError,
+    NotFoundError,
+    PayloadTooLargeError,
+    PaymentRequiredError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServiceUnavailableError,
+    UnprocessableEntityError,
+    UnsupportedMediaTypeError,
+)
+
+#: Every ``error.code`` a request can answer with (the API may add more; unknown codes map by HTTP status).
+API_ERROR_CODES: Tuple[str, ...] = ('INVALID_REQUEST', 'INVALID_FILENAME', 'INVALID_MEDIA_FORMAT', 'FILE_NOT_UPLOADED', 'FILE_TOO_LARGE', 'UPLOAD_ALREADY_USED', 'UPLOAD_EXPIRED', 'INVALID_API_KEY', 'API_KEY_REVOKED', 'INSUFFICIENT_BALANCE', 'ZERO_BALANCE', 'UPLOAD_NOT_FOUND', 'TRANSCRIPTION_NOT_FOUND', 'NOT_FOUND', 'FORBIDDEN', 'METHOD_NOT_ALLOWED', 'CONFLICT', 'PAYLOAD_TOO_LARGE', 'UNSUPPORTED_MEDIA_TYPE', 'IDEMPOTENCY_KEY_LOCKED', 'IDEMPOTENCY_KEY_CONFLICT', 'RATE_LIMIT_EXCEEDED', 'INTERNAL_ERROR', 'MAINTENANCE', 'ENDPOINT_REMOVED', 'ISSUER_UNCONFIGURED')
+
+#: The HTTP status each code is sent with.
+HTTP_STATUS_BY_CODE: Dict[str, int] = {"INVALID_REQUEST": 400, "INVALID_FILENAME": 400, "INVALID_MEDIA_FORMAT": 400, "FILE_NOT_UPLOADED": 400, "FILE_TOO_LARGE": 400, "UPLOAD_ALREADY_USED": 400, "UPLOAD_EXPIRED": 400, "INVALID_API_KEY": 401, "API_KEY_REVOKED": 401, "INSUFFICIENT_BALANCE": 402, "ZERO_BALANCE": 402, "UPLOAD_NOT_FOUND": 404, "TRANSCRIPTION_NOT_FOUND": 404, "NOT_FOUND": 404, "FORBIDDEN": 403, "METHOD_NOT_ALLOWED": 405, "CONFLICT": 409, "PAYLOAD_TOO_LARGE": 413, "UNSUPPORTED_MEDIA_TYPE": 415, "IDEMPOTENCY_KEY_LOCKED": 409, "IDEMPOTENCY_KEY_CONFLICT": 422, "RATE_LIMIT_EXCEEDED": 429, "INTERNAL_ERROR": 500, "MAINTENANCE": 503, "ENDPOINT_REMOVED": 410, "ISSUER_UNCONFIGURED": 503}
+
+# Codes a job can end with (status "failed", error.code). They never come back on the request itself:
+# wait() raises them as TranscriptionFailedError.
+#   URL_NOT_ACCESSIBLE: URL flow only. Covers several non-fetchable cases: the URL returned 4xx/5xx; DNS didn't resolve; the connection was refused; the response was an HTML page instead of media (login/preview/folder/expired-link); the share requires sign-in (e.g. OneDrive `1drv.ms/v/c/…` SharePoint Photos shares); or the server returned a 200 with an empty body. The `message` field names the specific cause when detectable.
+#   DOWNLOAD_FAILED: URL flow only: the download started but was interrupted.
+#   INVALID_MEDIA_FORMAT: The file downloaded but could not be read: not actually audio/video, no audio track, or **shorter than the 1-second minimum** (message names the measured duration, e.g. `"Audio too short (0.10s). Minimum duration is 1 second."`).
+#   FILE_TOO_LARGE: The file is larger than 5 GB. For a URL this is only known once the download reaches the limit.
+#   DURATION_TOO_LONG: Audio exceeds the 10-hour limit (only known after probing duration).
+#   INSUFFICIENT_BALANCE: Once the length was measured, the job cost more than your available balance. Nothing was charged. The `message` names the amount needed; add funds and submit again.
+#   PROCESSING_ERROR: Transcription failed after all retries.
+#   CREATED_TIMEOUT: Job sat in `created` for more than 30 minutes: the validation step never started.
+#   DOWNLOAD_TIMEOUT: Job sat in `downloading` for more than 15 minutes: the file download stalled.
+#   PROCESSING_TIMEOUT: Job sat in `processing` for more than 45 minutes without a result.
+#   BILLING_ERROR: Internal accounting issue while finalizing the charge. Your balance was **not** debited and the transcript was not delivered. Safe to retry.
+#   INTERNAL_ERROR: A server-side step (e.g. queueing the job to our processing layer) failed after we accepted the request. Safe to retry.
+#   CANCELLED: The transcription was cancelled by the customer via `POST /v1/transcribe/{id}/cancel`. You are not charged.
+TRANSCRIPTION_ERROR_CODES: Tuple[str, ...] = ('URL_NOT_ACCESSIBLE', 'DOWNLOAD_FAILED', 'INVALID_MEDIA_FORMAT', 'FILE_TOO_LARGE', 'DURATION_TOO_LONG', 'INSUFFICIENT_BALANCE', 'PROCESSING_ERROR', 'CREATED_TIMEOUT', 'DOWNLOAD_TIMEOUT', 'PROCESSING_TIMEOUT', 'BILLING_ERROR', 'INTERNAL_ERROR', 'CANCELLED')
+
+
+class InvalidRequestError(BadRequestError):
+    """``INVALID_REQUEST`` (HTTP 400). Malformed request body or missing required fields"""
+
+
+class InvalidFilenameError(BadRequestError):
+    """``INVALID_FILENAME`` (HTTP 400). Filename is missing, too long, contains invalid characters, or has no extension"""
+
+
+class InvalidMediaFormatError(BadRequestError):
+    """``INVALID_MEDIA_FORMAT`` (HTTP 400). Unsupported file extension at upload time (e.g. `.txt`, `.pdf`). Also returned later if the contents turn out not to be readable audio or video."""
+
+
+class FileNotUploadedError(BadRequestError):
+    """``FILE_NOT_UPLOADED`` (HTTP 400). File not found at the upload URL"""
+
+
+class FileTooLargeError(BadRequestError):
+    """``FILE_TOO_LARGE`` (HTTP 400). File exceeds 5 GB limit"""
+
+
+class UploadAlreadyUsedError(BadRequestError):
+    """``UPLOAD_ALREADY_USED`` (HTTP 400). Upload already used for a transcription"""
+
+
+class UploadExpiredError(BadRequestError):
+    """``UPLOAD_EXPIRED`` (HTTP 400). Upload URL expired (1 hour TTL)"""
+
+
+class InvalidApiKeyError(AuthenticationError):
+    """``INVALID_API_KEY`` (HTTP 401). Invalid or missing API key"""
+
+
+class ApiKeyRevokedError(AuthenticationError):
+    """``API_KEY_REVOKED`` (HTTP 401). API key has been revoked"""
+
+
+class InsufficientBalanceError(PaymentRequiredError):
+    """``INSUFFICIENT_BALANCE`` (HTTP 402). Not enough balance for this transcription"""
+
+
+class ZeroBalanceError(PaymentRequiredError):
+    """``ZERO_BALANCE`` (HTTP 402). Balance is $0 or below: deposit required"""
+
+
+class UploadNotFoundError(NotFoundError):
+    """``UPLOAD_NOT_FOUND`` (HTTP 404). Upload ID does not exist"""
+
+
+class TranscriptionNotFoundError(NotFoundError):
+    """``TRANSCRIPTION_NOT_FOUND`` (HTTP 404). Transcription ID does not exist"""
+
+
+class ForbiddenError(PermissionDeniedError):
+    """``FORBIDDEN`` (HTTP 403). Request rejected upstream (e.g. by the network layer) before it reached the API."""
+
+
+class IdempotencyKeyLockedError(ConflictError):
+    """``IDEMPOTENCY_KEY_LOCKED`` (HTTP 409). Another request with the same `Idempotency-Key` is mid-flight. Retry after a few seconds (`Retry-After` header sent)."""
+
+
+class IdempotencyKeyConflictError(UnprocessableEntityError):
+    """``IDEMPOTENCY_KEY_CONFLICT`` (HTTP 422). `Idempotency-Key` reused with a different request body. Use a fresh key for a different operation."""
+
+
+class RateLimitExceededError(RateLimitError):
+    """``RATE_LIMIT_EXCEEDED`` (HTTP 429). Too many requests (see Rate Limits), or 25 jobs already in progress on POST /v1/transcribe"""
+
+
+class InternalError(InternalServerError):
+    """``INTERNAL_ERROR`` (HTTP 500). Server error"""
+
+
+class MaintenanceError(ServiceUnavailableError):
+    """``MAINTENANCE`` (HTTP 503). The API is briefly paused for maintenance. Nothing was created or charged. Retry after the number of seconds in the `Retry-After` header."""
+
+
+class EndpointRemovedError(GoneError):
+    """``ENDPOINT_REMOVED`` (HTTP 410). This endpoint has been removed. The `message` says what to use instead (for `POST /v1/accounts`: create the account at https://www.scriptivox.com/signup)."""
+
+
+class IssuerUnconfiguredError(ServiceUnavailableError):
+    """``ISSUER_UNCONFIGURED`` (HTTP 503). OAuth sign-in is not configured on this deployment."""
+
+
+#: The class raised for each code.
+ERROR_CLASS_BY_CODE: Dict[str, Type[APIError]] = {
+    "INVALID_REQUEST": InvalidRequestError,
+    "INVALID_FILENAME": InvalidFilenameError,
+    "INVALID_MEDIA_FORMAT": InvalidMediaFormatError,
+    "FILE_NOT_UPLOADED": FileNotUploadedError,
+    "FILE_TOO_LARGE": FileTooLargeError,
+    "UPLOAD_ALREADY_USED": UploadAlreadyUsedError,
+    "UPLOAD_EXPIRED": UploadExpiredError,
+    "INVALID_API_KEY": InvalidApiKeyError,
+    "API_KEY_REVOKED": ApiKeyRevokedError,
+    "INSUFFICIENT_BALANCE": InsufficientBalanceError,
+    "ZERO_BALANCE": ZeroBalanceError,
+    "UPLOAD_NOT_FOUND": UploadNotFoundError,
+    "TRANSCRIPTION_NOT_FOUND": TranscriptionNotFoundError,
+    "NOT_FOUND": NotFoundError,
+    "FORBIDDEN": ForbiddenError,
+    "METHOD_NOT_ALLOWED": MethodNotAllowedError,
+    "CONFLICT": ConflictError,
+    "PAYLOAD_TOO_LARGE": PayloadTooLargeError,
+    "UNSUPPORTED_MEDIA_TYPE": UnsupportedMediaTypeError,
+    "IDEMPOTENCY_KEY_LOCKED": IdempotencyKeyLockedError,
+    "IDEMPOTENCY_KEY_CONFLICT": IdempotencyKeyConflictError,
+    "RATE_LIMIT_EXCEEDED": RateLimitExceededError,
+    "INTERNAL_ERROR": InternalError,
+    "MAINTENANCE": MaintenanceError,
+    "ENDPOINT_REMOVED": EndpointRemovedError,
+    "ISSUER_UNCONFIGURED": IssuerUnconfiguredError,
+}
+
+__all__ = [
+    "API_ERROR_CODES",
+    "HTTP_STATUS_BY_CODE",
+    "TRANSCRIPTION_ERROR_CODES",
+    "ERROR_CLASS_BY_CODE",
+    "InvalidRequestError",
+    "InvalidFilenameError",
+    "InvalidMediaFormatError",
+    "FileNotUploadedError",
+    "FileTooLargeError",
+    "UploadAlreadyUsedError",
+    "UploadExpiredError",
+    "InvalidApiKeyError",
+    "ApiKeyRevokedError",
+    "InsufficientBalanceError",
+    "ZeroBalanceError",
+    "UploadNotFoundError",
+    "TranscriptionNotFoundError",
+    "ForbiddenError",
+    "IdempotencyKeyLockedError",
+    "IdempotencyKeyConflictError",
+    "RateLimitExceededError",
+    "InternalError",
+    "MaintenanceError",
+    "EndpointRemovedError",
+    "IssuerUnconfiguredError",
+]

scriptivox/_exceptions.py

@@ -0,0 +1,196 @@
+"""Exceptions. Everything the SDK raises extends ScriptivoxError.
+
+    ScriptivoxError
+    ├── APIError                        the API answered with an error (status, code, request_id)
+    │   ├── BadRequestError (400)       ├── InvalidRequestError, InvalidFilenameError, ... (one per error.code,
+    │   ├── AuthenticationError (401)   │   generated in _error_codes.py from the OpenAPI document)
+    │   ├── PaymentRequiredError (402)  ├── InsufficientBalanceError, ZeroBalanceError
+    │   ├── ... one class per HTTP status the API uses
+    │   └── RateLimitError (429)        └── RateLimitExceededError
+    ├── APIConnectionError              no answer: DNS, refused, reset (APITimeoutError: no answer in time)
+    ├── UploadFailedError               the file PUT to the presigned upload URL failed
+    ├── TranscriptionFailedError        wait(): the job ended with status "failed" (code = the job's error.code)
+    ├── WaitTimeoutError                wait(): the job was still running when the timeout passed
+    └── WebhookVerificationError        verify_webhook(): bad signature, old timestamp, missing header
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional, Type
+
+
+class ScriptivoxError(Exception):
+    """Base class of every error the SDK raises."""
+
+
+class APIError(ScriptivoxError):
+    """The API answered with an HTTP error. Branch on ``code`` (stable) or the class; never on the message."""
+
+    def __init__(
+        self,
+        *,
+        status: int,
+        code: str,
+        message: str,
+        request_id: Optional[str] = None,
+        docs_url: Optional[str] = None,
+        retry_after: Optional[float] = None,
+        error: Optional[Dict[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> None:
+        ref = ", ".join(x for x in (code, f"request {request_id}" if request_id else None) if x)
+        super().__init__(f"{message} [{ref}]")
+        #: HTTP status.
+        self.status = status
+        #: The API's machine-readable ``error.code``, e.g. "ZERO_BALANCE"; "UNKNOWN_ERROR" when the body had none.
+        self.code = code
+        #: The server's message (without the bracketed code and request id).
+        self.message = message
+        #: ``X-Request-Id`` / ``error.request_id`` (``req_`` + 16 hex). Quote it to support.
+        self.request_id = request_id
+        self.docs_url = docs_url
+        #: Seconds from the ``Retry-After`` header, when the answer had one.
+        self.retry_after = retry_after
+        #: The whole ``error`` object (extra fields such as ``in_flight`` and ``limit`` live here).
+        self.error: Dict[str, Any] = dict(error or {})
+        #: Response headers, lower-case names.
+        self.headers: Dict[str, str] = {k.lower(): v for k, v in (headers or {}).items()}
+
+
+class BadRequestError(APIError):
+    pass
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class PaymentRequiredError(APIError):
+    pass
+
+
+class PermissionDeniedError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class MethodNotAllowedError(APIError):
+    pass
+
+
+class ConflictError(APIError):
+    pass
+
+
+class GoneError(APIError):
+    pass
+
+
+class PayloadTooLargeError(APIError):
+    pass
+
+
+class UnsupportedMediaTypeError(APIError):
+    pass
+
+
+class UnprocessableEntityError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    pass
+
+
+class InternalServerError(APIError):
+    pass
+
+
+class ServiceUnavailableError(APIError):
+    pass
+
+
+_CATEGORY_BY_STATUS: Dict[int, Type[APIError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: PaymentRequiredError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    405: MethodNotAllowedError,
+    409: ConflictError,
+    410: GoneError,
+    413: PayloadTooLargeError,
+    415: UnsupportedMediaTypeError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+    503: ServiceUnavailableError,
+}
+
+
+def category_for_status(status: int) -> Type[APIError]:
+    """The category class for an HTTP status, used when a code is not one the SDK knows."""
+    if status in _CATEGORY_BY_STATUS:
+        return _CATEGORY_BY_STATUS[status]
+    return InternalServerError if status >= 500 else APIError
+
+
+class APIConnectionError(ScriptivoxError):
+    """No HTTP answer at all: DNS failure, connection refused or reset."""
+
+
+class APITimeoutError(APIConnectionError):
+    """No answer within the request timeout."""
+
+
+class UploadFailedError(ScriptivoxError):
+    """The PUT of the file bytes to the presigned upload URL failed."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None, body: Optional[str] = None) -> None:
+        super().__init__(message)
+        #: HTTP status from the storage server, when it answered.
+        self.status = status
+        #: The start of the storage server's answer (often XML).
+        self.body = body
+
+
+class TranscriptionFailedError(ScriptivoxError):
+    """wait(): the job ended with ``status: "failed"``. Failed jobs cost nothing.
+
+    ``code`` is the job's ``error.code`` (URL_NOT_ACCESSIBLE, INVALID_MEDIA_FORMAT, CANCELLED, ...);
+    ``transcription`` is the job.
+    """
+
+    def __init__(self, transcription: Mapping[str, Any]) -> None:
+        error = transcription.get("error") or {}
+        self.code: str = error.get("code") or "UNKNOWN_ERROR"
+        self.transcription_id: str = transcription.get("id", "")
+        self.transcription: Dict[str, Any] = dict(transcription)
+        message = error.get("message") or "The transcription failed."
+        super().__init__(f"Transcription {self.transcription_id} failed: {message} [{self.code}]")
+
+
+class WaitTimeoutError(ScriptivoxError):
+    """wait(): the timeout passed while the job was still running. The job carries on; wait again later."""
+
+    def __init__(self, transcription: Mapping[str, Any], timeout: float) -> None:
+        self.transcription_id: str = transcription.get("id", "")
+        #: The last status seen.
+        self.transcription: Dict[str, Any] = dict(transcription)
+        super().__init__(
+            f'Transcription {self.transcription_id} is still "{transcription.get("status")}" after {round(timeout)} s. '
+            "It carries on running; call wait() again or get() later."
+        )
+
+
+class WebhookVerificationError(ScriptivoxError):
+    """verify_webhook(): not a genuine, fresh Scriptivox webhook. Answer such a request with 400.
+
+    ``reason`` is one of: missing_header, invalid_timestamp, timestamp_outside_tolerance,
+    signature_mismatch, invalid_json.
+    """
+
+    def __init__(self, reason: str, message: str) -> None:
+        super().__init__(message)
+        self.reason = reason