Guides

Troubleshooting

Common production issues and how to resolve them quickly.

Common Issues

Symptom	Likely Cause	Action
Job stays processing for too long	Queue backlog or large media	Poll with backoff and set timeout guardrails
401/invalid_api_key	Wrong key or key disabled	Rotate key and verify environment mapping
402/insufficient_credits	Account credits below required amount	Top up credits before retry
Loss of fine details	Model/format mismatch	Try original or pro, use higher source quality, avoid aggressive compression
Flicker between frames	Scene complexity + unstable segmentation	Use original/pro, avoid aggressive post smoothing, test on representative clips

Debug Checklist

Log request body (without secrets), model, format, and response status.
Log job_id and correlate with server-side usage events.
Check /health and /api/pricing to verify runtime config.
Validate output format capability for transparency use cases.

Escalation Data to Include

job_id and request timestamp
model, output_format, and background/composition payload
source video metadata (duration, resolution, codec)
full error response body and HTTP status

Quality Guardrails

Prefer representative source clips when tuning model defaults.
Keep input compression moderate to preserve edge details.
Use explicit output format policy for transparent vs non-transparent workflows.
Run A/B validation with the same clip set before changing defaults.

Implementation Checklist

Define payload schema validation in backend before forwarding requests.
Store model/output_format/background settings with each job record.
Add internal quality review for difficult scenes (hair, glass, motion blur).
Create runbook entries for model-specific failure cases.

Incident Report Template

{
  "incident_time": "2026-04-20T10:00:00Z",
  "job_id": "job_xxx",
  "model": "pro",
  "output_format": "webm",
  "symptom": "flicker / detail loss / timeout",
  "http_status": 500,
  "error_code": "internal_error",
  "request_id": "req_xxx",
  "source_video_meta": {
    "duration_s": 12.3,
    "resolution": "1920x1080",
    "codec": "h264"
  }
}

Retry Strategy

Introduction