Errors
Error states are part of the API contract.
A credible video API tells developers when it cannot answer, when an artifact is not ready, and when human review is required.
Error catalog
| Code | Meaning |
|---|---|
| AUTH_REQUIRED | Missing or invalid session/API key. Route to sign-in or key rotation. |
| VALIDATION_FAILED | Malformed body, missing source URL, unsupported metadata, or bad tenant context. |
| LIMIT_EXCEEDED | Workspace exceeded videos, capture seconds, API calls, storage, active jobs, or Ask quota. |
| EXECUTION_NOT_READY | The video exists but no execution has started or completed. |
| ARTIFACT_NOT_READY | The JSON artifact has not been materialized for the latest execution. |
| INSUFFICIENT_EVIDENCE | The answer cannot be supported by available evidence spans. |
| REVIEW_REQUIRED | The workflow is ambiguous, high-risk, or outside safe beta automation boundaries. |
Error envelope
{
"ok": false,
"request_id": "req_...",
"error": {"code": "INSUFFICIENT_EVIDENCE", "message": "No evidence span supports this answer.", "review_required": true, "retryable": false}
}UI handling rules
AUTH_REQUIRED should route to login or key rotation. LIMIT_EXCEEDED should show current usage. ARTIFACT_NOT_READY should show a waiting state. INSUFFICIENT_EVIDENCE should show that the system refused to guess. REVIEW_REQUIRED should create a human review task for high-risk workflows.
Retry network failures and waiting states with backoff. Do not retry validation errors or insufficient evidence. Re-running execution may change cost and artifacts, so it should be a visible action.