# Common Drift and Breaks

## 1. Auth fails even though credentials look correct

Likely causes:
- wrong credential pair from the portal
- expired JWT
- mixing Build-platform credentials with non-Build Zoom app credentials
- valid-looking key/secret pair that is not authorized for AI Services Scribe

Check:
- `iss` value
- `exp` window
- current credential labels in portal
- if the API responds with `{"code":124,"message":"Invalid Access token"}`, treat that as a real upstream auth failure, not a transport problem

## 2. Fast mode request shape mismatch

Docs show JSON with `file` URL, but the official quickstart also proxies multipart upload and forwards a `FormData` request.

Use one clear model per service boundary:
- client upload -> your backend multipart
- backend upload proxy -> `multipart/form-data` to `/aiservices/scribe/transcribe`
- backend URL-based submit -> JSON body with `file` URL

Symptoms:
- browser request stays pending for a long time
- backend eventually returns timeout or empty upstream reply

Preferred fix:
- treat uploaded files and URL-based files as two separate request paths instead of forcing both through one JSON shape

## 3. Fast mode returns `413 Request Entity Too Large`

Likely cause:
- reverse proxy rejected the upload before the request reached your app

Known deployment check:
- if nginx fronts the app, raise `client_max_body_size` to match or exceed your server-side upload limit

Current Scribe fast-mode API limits:
- maximum file size: `100 MB`
- maximum duration: `2 hours`

## 4. Fast mode returns `504 Gateway time-out`

Likely cause:
- the request reached your backend, but synchronous processing took too long for the edge/proxy path

Observed deployment behavior:
- public HTTPS can time out even when the same request path is valid and the backend is healthy
- observed hosted sample timings:
  - ~17.2 MB MP4: ~26s
  - ~38.6 MB MP4: ~26-37s
  - ~59.2 MB MP4: ~32-34s backend completion, but some browser requests still timed out first

Guardrail:
- use fast mode for smaller, interactive files
- use batch mode for large uploads or longer media where waiting synchronously through the web UI is brittle
- add request-level logging for:
  - file name
  - file size
  - mime type
  - upstream elapsed time
  - response payload size and top-level keys
  so you can tell whether the origin completed successfully while the browser/edge timed out
- for hosted UIs, wrap fast mode in an async request/polling flow instead of holding the browser open for the entire upstream response
- if nginx access logs show `499` while app logs later show `zoom_request_finished status: 200`, the transcription succeeded and only the browser-side request path was lost

## 5. Batch job accepted but outputs never appear

Likely causes:
- S3 URI/auth mismatch
- expired STS credentials
- output layout/URI mismatch
- webhook endpoint unreachable if you rely on callbacks

Check:
- `/jobs/{jobId}` summary
- `/jobs/{jobId}/files`
- cloud storage permissions

## 6. Webhook verification fails

Current sample pattern uses:
- `x-zm-signature`
- `x-zm-request-timestamp`
- HMAC-SHA256 with `sha256=` prefix

If verification fails:
- confirm raw body capture before JSON parsing
- confirm timestamp header was included in the signed string
- confirm the shared secret matches the job notification config

## 7. Health check says credentials exist, but API calls still fail

Likely cause:
- environment file contains literal placeholders such as `${ZOOM_API_KEY}` or `${ZOOM_API_SECRET}`

Guardrail:
- only treat credentials as present if they are real values, not unresolved shell placeholders
- fail fast with a clear credential error before attempting Zoom calls

## 8. Wrong product chosen

Symptoms:
- trying to use Scribe for live in-meeting media
- trying to use RTMS for offline archive transcription

Guardrail:
- file/storage transcription -> `scribe`
- live meeting media -> `rtms`

## 9. Browser microphone chunk 1 works but later chunks are empty

Likely cause:
- the browser emitted a valid first container chunk, but later `MediaRecorder` timeslice blobs were partial WebM/Opus clusters without fresh container headers

Symptoms:
- chunk 1 transcribes normally
- chunk 2 onward returns empty transcript text or much weaker results
- auth and request flow still look healthy

Preferred fix:
- do not rely on one long `MediaRecorder.start(timeslice)` session for standalone chunk uploads
- rotate the recorder per chunk instead:
  - start recorder
  - record one chunk window
  - stop recorder
  - upload that blob
  - start a new recorder for the next chunk

Guardrail:
- treat browser microphone pseudo-streaming as a file-container problem first, not a Scribe-language-model problem