Troubleshooting


Getting started	The common cases — auth errors, validation, ingest warnings, sync timeouts. Start here.
Templates	Template-specific errors — TEMPLATE_FAILED, missing variables, grammar mistakes.
Rendering + jobs	Render failures, sync timeouts, job-stuck-pending, presigned URL issues.
Ingestion	Format detection, fidelity-warning catalogue, slow-path recovery.

Where to look first when stuck#

The error envelope. Every 4xx/5xx response carries error.code, error.message, error.details, error.request_id. The code is machine-readable; the message is operator-readable; request_id lets you grep the backend logs.
The fidelity warnings. Ingest responses always include spec.fidelity.warnings[] with structured codes — INGEST_* codes are documented and tell you exactly what didn't survive.
The job result_json. GET /v1/jobs/{job_id} returns the full structured error from the worker side when a render fails — usually more detail than the 500 response carried.
The access log. uvicorn JSON access log on the backend host shows every request with its request_id, status, and timing. Grep by request_id to pull the matching server-side log.

When something is genuinely broken, include in the bug report:

The full error envelope (especially request_id).
The full request (method, path, body, headers minus auth).
The SDK version (Python pip show scaiscribe; TS npm list @scaiscribe/sdk; .NET dotnet list package).
ScaiScribe backend version, if you have it (visible in /v1/health response).

request_id is the most useful single field — operators can grep for it across api + worker logs and reconstruct the entire request lifecycle.