2.0.0: API v2

Targets /api/v2: one error block on every failure (code, number, message,
docs, retry_with | details | issues), family-based exception classes
(NotFoundError, BatchTooLargeError, UnprocessableInputError), ApiErrorBlock
model, batch entries with three outcomes and an error block,
Transcript.source and Transcript.error. v1 stays reachable until
2027-09-03; 1.x keeps working.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014Pvnuti4G9iijR3mRCw9CH

Author: Chandler Casey

CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org).
 
+## [2.0.0] - 2026-09-03
+
+Targets API v2 (`/api/v2`). v1 is deprecated server-side with a twelve-month
+window, so 1.x keeps working until 2027-09-03; upgrade before then.
+
+### Breaking
+
+- Every request goes to `/api/v2/...`.
+- `APIError` gains `number` (stable integer code; the thousands digit is the
+  family, 5xxx = retry), `docs`, `retry_with`, `details`, and a `retryable`
+  property. New subclasses: `NotFoundError` (404), `BatchTooLargeError` (400,
+  `details["max"]`), `UnprocessableInputError` (422, the whole 3xxx/4xxx
+  family: unsupported platform, no captions, private, live, and so on;
+  `retry_with` is set when a different request would work, e.g.
+  `{"mode": "audio"}`).
+- `BatchResult`: `outcome` is exactly `"ok" | "processing" | "error"`; the
+  deprecated `cached` and `status` fields are gone; failed entries carry
+  `error` (an `ApiErrorBlock`, the same shape a request-level error raises);
+  `source` and `poll_url` added.
+- `Transcript.error` (an `ApiErrorBlock`) is set on a failed job polled via
+  `transcripts.job()`.
+
+### Added
+
+- `Transcript.source`: `"captions"` or `"audio"`, where the words came from.
+- `ApiErrorBlock` model.
+
 ## [1.0.2] - 2026-08-28
 
 Batch grew audio fallback on the API side; this release types it.

README.md

@@ -66,7 +66,7 @@ print(t.podcast.show, "-", t.podcast.episode)
 
 Podcast transcriptions include best-effort speaker diarization: each segment may carry a `speaker` integer (0, 1, …) identifying who is talking. The ids are hints from voice separation, not named identification, and non-podcast sources never carry them.
 
-Batch works the same way by default (`mode="auto"`): entries with no caption track are transcribed from audio, come back with `outcome == "processing"` and a `job_id`, cost nothing on that call, and are charged on delivery at the audio rate. Re-send the same batch once the jobs have had time to finish and the text comes back normally — or poll each `job_id` with `tf.transcripts.job()`. Pass `mode="captions"` to read existing caption tracks only, in which case a captionless video fails as `no_transcript` (the old behaviour):
+Batch works the same way by default (`mode="auto"`): entries with no caption track are transcribed from audio, come back with `outcome == "processing"` and a `job_id`, cost nothing on that call, and are charged on delivery at the audio rate. Re-send the same batch once the jobs have had time to finish and the text comes back normally — or poll each `job_id` with `tf.transcripts.job()`. Pass `mode="captions"` to read existing caption tracks only, in which case a captionless video fails as `outcome == "error"` with `error.code == "no_captions"` (and `error.retry_with` naming the audio mode):
 
 ```python
 res = tf.transcripts.batch(ids)                    # captionless entries -> "processing" + job_id
@@ -104,7 +104,7 @@ asyncio.run(main())
 
 ## Errors
 
-All errors subclass `TranscriptFetchError`. API errors carry `.status`, `.code`, `.message`, and `.request_id`:
+All errors subclass `TranscriptFetchError`. API errors carry `.status`, `.code`, `.number` (the thousands digit is the family; 5xxx means retry), `.message`, `.docs`, `.retry_with` (the request change that would succeed, when there is one), `.details`, `.request_id`, and a `.retryable` property:
 
 ```python
 from transcriptfetch import (

src/transcriptfetch/__init__.py

@@ -18,7 +18,10 @@
     APITimeoutError,
     AuthenticationError,
     IdempotencyConflictError,
+    BatchTooLargeError,
     InsufficientCreditsError,
+    NotFoundError,
+    UnprocessableInputError,
     InternalServerError,
     InvalidRequestError,
     RateLimitError,
@@ -28,6 +31,7 @@
 from .models import (
     Account,
     BatchResponse,
+    ApiErrorBlock,
     BatchResult,
     Podcast,
     Segment,
@@ -49,6 +53,7 @@
     "Transcript",
     "Video",
     "VideoList",
+    "ApiErrorBlock",
     "BatchResult",
     "BatchResponse",
     # errors
@@ -58,7 +63,10 @@
     "APITimeoutError",
     "AuthenticationError",
     "InvalidRequestError",
+    "BatchTooLargeError",
     "InsufficientCreditsError",
+    "NotFoundError",
+    "UnprocessableInputError",
     "IdempotencyConflictError",
     "RateLimitError",
     "UpstreamUnavailableError",

src/transcriptfetch/_version.py

@@ -1 +1 @@
-__version__ = "1.0.2"
+__version__ = "2.0.0"

src/transcriptfetch/async_client.py

@@ -82,14 +82,14 @@ async def _request(
 
     async def me(self) -> Account:
         """Validate the API key and read the account's credit balance. Free."""
-        env = await self._request("GET", "/api/v1/me")
+        env = await self._request("GET", "/api/v2/me")
         account = Account.model_validate(env.get("data") or {})
         account.usage = parse_usage(env)
         return account
 
     async def health(self) -> dict[str, Any]:
         """Unauthenticated liveness probe."""
-        return await self._request("GET", "/api/v1/health", auth=False)
+        return await self._request("GET", "/api/v2/health", auth=False)
 
     async def close(self) -> None:
         if self._owns_http:

src/transcriptfetch/client.py

@@ -79,14 +79,14 @@ def _request(
 
     def me(self) -> Account:
         """Validate the API key and read the account's credit balance. Free."""
-        env = self._request("GET", "/api/v1/me")
+        env = self._request("GET", "/api/v2/me")
         account = Account.model_validate(env.get("data") or {})
         account.usage = parse_usage(env)
         return account
 
     def health(self) -> dict[str, Any]:
         """Unauthenticated liveness probe."""
-        return self._request("GET", "/api/v1/health", auth=False)
+        return self._request("GET", "/api/v2/health", auth=False)
 
     def close(self) -> None:
         if self._owns_http:

src/transcriptfetch/errors.py

@@ -1,8 +1,15 @@
 """Exception hierarchy for the TranscriptFetch SDK.
 
-The API returns a canonical error envelope: ``{ ok: false, request_id, error:
-{ code, message, issues? } }``. We map ``error.code`` (falling back to the HTTP
-status) to a specific exception subclass so callers can branch cleanly.
+The API (v2) returns one error block on every failure::
+
+    { "ok": false, "request_id": "...",
+      "error": { "code", "number", "message", "docs", "retry_with"?, "details"?, "issues"? } }
+
+``code`` is a stable string and ``number`` a stable integer whose thousands
+digit is the family (1 request, 2 account, 3 input, 4 content, 5 transient,
+9 ours). We map ``error.code`` (falling back to the number's family, then the
+HTTP status) to a specific exception subclass so callers can branch cleanly,
+and expose the rest of the block as attributes.
 """
 
 from __future__ import annotations
@@ -31,21 +38,49 @@ def __init__(
         *,
         status: int,
         code: Optional[str] = None,
+        number: Optional[int] = None,
         request_id: Optional[str] = None,
+        docs: Optional[str] = None,
+        retry_with: Optional[dict[str, Any]] = None,
+        details: Optional[dict[str, Any]] = None,
         issues: Optional[list[Any]] = None,
     ) -> None:
         super().__init__(message)
         self.status = status
         self.code = code
+        self.number = number
+        """Stable numeric code; the thousands digit is the family."""
         self.message = message
         self.request_id = request_id
+        self.docs = docs
+        """Per-code documentation URL."""
+        self.retry_with = retry_with
+        """The request change that would succeed, e.g. ``{"mode": "audio"}``, else ``None``."""
+        self.details = details
+        """Structured specifics for the few codes that document them."""
         self.issues = issues or []
 
+    @property
+    def retryable(self) -> bool:
+        """Whether the SAME request is worth retrying with backoff.
+
+        True for the transient (5xxx) and server (9xxx) families, plus rate
+        limits and credit exhaustion once the condition clears. Never true for
+        1xxx/3xxx/4xxx, where the request itself has to change (see
+        ``retry_with``).
+        """
+        if self.number is not None:
+            family = self.number // 1000
+            return family in (5, 9) or self.code in ("rate_limited", "insufficient_credits")
+        return self.status == 429 or self.status >= 500
+
     def __str__(self) -> str:
         bits = [self.message]
         meta = [f"status={self.status}"]
         if self.code:
             meta.append(f"code={self.code}")
+        if self.number is not None:
+            meta.append(f"number={self.number}")
         if self.request_id:
             meta.append(f"request_id={self.request_id}")
         bits.append(f"[{', '.join(meta)}]")
@@ -57,7 +92,15 @@ class AuthenticationError(APIError):
 
 
 class InvalidRequestError(APIError):
-    """400: the request body failed validation (see ``issues``)."""
+    """400: the request body failed validation (see ``issues``), or a stale cursor."""
+
+
+class BatchTooLargeError(InvalidRequestError):
+    """400 ``batch_too_large``: over your plan's per-batch cap (see ``details["max"]``)."""
+
+
+class NotFoundError(APIError):
+    """404: no such job for this account."""
 
 
 class InsufficientCreditsError(APIError):
@@ -76,10 +119,20 @@ def __init__(self, message: str, *, retry_after: Optional[float] = None, **kwarg
         self.retry_after = retry_after
 
 
+class UnprocessableInputError(APIError):
+    """422: this input cannot be served, permanently (the 3xxx and 4xxx families).
+
+    An unsupported platform, the wrong endpoint for the platform, a podcast
+    with no public feed, a private or live video, no captions, no speech.
+    ``code`` says which; ``retry_with`` is set when a different request would
+    work (e.g. ``{"mode": "audio"}`` to transcribe a captionless video).
+    """
+
+
 class UpstreamUnavailableError(APIError):
     """502/503: the upstream platform blocked or was unreachable. Safe to retry.
 
-    Upstream platform blocks answer 503 with code ``upstream_error`` — never
+    Upstream platform blocks answer 503 with code ``upstream_error``, never
     429, which is reserved for per-key rate limits (:class:`RateLimitError`).
     """
 
@@ -91,26 +144,45 @@ class InternalServerError(APIError):
 _CODE_TO_EXC: dict[str, type[APIError]] = {
     "unauthorized": AuthenticationError,
     "invalid_request": InvalidRequestError,
+    "invalid_cursor": InvalidRequestError,
+    "not_found": NotFoundError,
     "insufficient_credits": InsufficientCreditsError,
+    "batch_too_large": BatchTooLargeError,
     "idempotency_conflict": IdempotencyConflictError,
     "rate_limited": RateLimitError,
     "upstream_unavailable": UpstreamUnavailableError,
-    "upstream_error": UpstreamUnavailableError,
     "internal_error": InternalServerError,
 }
 
 _STATUS_TO_EXC: dict[int, type[APIError]] = {
     400: InvalidRequestError,
     401: AuthenticationError,
     402: InsufficientCreditsError,
+    404: NotFoundError,
     409: IdempotencyConflictError,
+    422: UnprocessableInputError,
     429: RateLimitError,
     500: InternalServerError,
     502: UpstreamUnavailableError,
     503: UpstreamUnavailableError,
 }
 
 
+def _exc_for(code: Optional[str], number: Optional[int], status: int) -> type[APIError]:
+    """Choose the class from the number's family when the code is not listed."""
+    if code and code in _CODE_TO_EXC:
+        return _CODE_TO_EXC[code]
+    if number is not None:
+        family = number // 1000
+        if family in (3, 4):
+            return UnprocessableInputError
+        if family == 5:
+            return UpstreamUnavailableError
+        if family == 9:
+            return InternalServerError
+    return _STATUS_TO_EXC.get(status, APIError)
+
+
 def raise_api_error(
     status: int,
     payload: dict[str, Any],
@@ -120,16 +192,35 @@ def raise_api_error(
     """Map an error response to the appropriate exception and raise it."""
     error = payload.get("error") if isinstance(payload, dict) else None
     code: Optional[str] = None
+    number: Optional[int] = None
     message = f"Request failed with status {status}"
+    docs: Optional[str] = None
+    retry_with: Optional[dict[str, Any]] = None
+    details: Optional[dict[str, Any]] = None
     issues: Optional[list[Any]] = None
     if isinstance(error, dict):
         code = error.get("code")
+        raw_number = error.get("number")
+        number = raw_number if isinstance(raw_number, int) else None
         message = error.get("message") or message
+        docs = error.get("docs") if isinstance(error.get("docs"), str) else None
+        retry_with = error.get("retry_with") if isinstance(error.get("retry_with"), dict) else None
+        details = error.get("details") if isinstance(error.get("details"), dict) else None
         raw_issues = error.get("issues")
         if isinstance(raw_issues, list):
             issues = raw_issues
 
-    exc_cls = (code and _CODE_TO_EXC.get(code)) or _STATUS_TO_EXC.get(status) or APIError
+    exc_cls = _exc_for(code, number, status)
+    kwargs: dict[str, Any] = dict(
+        status=status,
+        code=code,
+        number=number,
+        request_id=request_id,
+        docs=docs,
+        retry_with=retry_with,
+        details=details,
+        issues=issues,
+    )
 
     if exc_cls is RateLimitError:
         parsed_retry: Optional[float] = None
@@ -138,13 +229,6 @@ def raise_api_error(
                 parsed_retry = float(retry_after)
             except (TypeError, ValueError):
                 parsed_retry = None
-        raise RateLimitError(
-            message,
-            status=status,
-            code=code,
-            request_id=request_id,
-            issues=issues,
-            retry_after=parsed_retry,
-        )
-
-    raise exc_cls(message, status=status, code=code, request_id=request_id, issues=issues)
+        raise RateLimitError(message, retry_after=parsed_retry, **kwargs)
+
+    raise exc_cls(message, **kwargs)