Document Spotify ingest failure states and album routing

SI
5d ago
+4-4

Summary

Documents the contract for the Context ingest failure states that the companion API PR implements. The ingest url description now states that album URLs are routed to ingest_release and that playlists, artist pages and YouTube are rejected with an explicit message; the 400 description says issues[] carries that routing message; the 200 (read) description defines request.error as <code>: <recovery guidance> with the code list (unsupported_input, recording_unavailable, provider_outage, provider_rejected, provider_response_invalid, identity_conflict, unknown) and the same-idempotency-key retry rule; the 409 description clarifies that a background extraction failure is read from the request, not returned as a 409. This advances the ticket's "malformed/unavailable URLs and provider errors produce recoverable states" and "route unsupported album/playlist inputs explicitly" items.

Refs recoupable/app#2126 (child of epic recoupable/app#2116).

Merge sequencing

docs → database → api → app. This docs PR merges first. Companion API PR: recoupable/api "Persist distinct recoverable Spotify ingest failure states" on branch claude/ctx-2126-ingest-failure-states. No database or app change in this slice. Depends on no open PR.

Verification

  • Ran: python3 -c "import json;json.load(open('api-reference/openapi/context.json'))" → parses.
  • Ran: git diff --stat origin/main | grep -c '|' → 1 (only api-reference/openapi/context.json, 4 insertions / 4 deletions, additive anchored text edits).
  • Ran: grep -c 'ingest_release' api-reference/openapi/context.json → 2.
  • Red → green: not applicable (documentation only); the behavior is fixture-tested in the API PR (lib/context/__tests__/ingestFailureStates.test.ts, 42 tests).
  • Not verified: hosted Mintlify deployment, live providers, production database.

Out of scope / known gaps

  • HTTP status differentiation at the handler (every thrown operation error is still a 409 string).
  • Guest path (fail_context_guest stores no error text).
  • Retaining the originally submitted locator (intl-xx, ?si) alongside the canonical URL.
  • YouTube ingestion and any paid module.

🤖 Generated with Claude Code

Summary by cubic

Documents the recoverable failure states for Spotify Context ingest in the API reference, replacing the single fixed error string with structured guidance so callers can tell why a request failed.

  • Failed ingest requests report request.error as <code>: <recovery guidance>, covering unsupported_input, recording_unavailable, provider_outage, provider_rejected, provider_response_invalid, identity_conflict, and unknown; rerunning ingest with the same idempotency key re-claims a failed request.
  • Album URLs now route to ingest_release; playlists, artist pages, and YouTube are rejected with routing guidance in the 400 issues[] message.
  • Background extraction failures are exposed via read on the 202 request and are no longer documented as a 409.