Error Handling

Handling Pattern

1. Catch and classify error type.
2. Retry only transient errors.
3. Capture request_id/job_id in logs.
4. Escalate permanent errors to user-facing state.

Sample Error Envelope

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to process this video",
    "request_id": "req_123456"
  }
}

Recommended SDK Usage Pattern

1. Initialize singleton client per service process.
2. Wrap SDK calls with your own timeout/retry decorators.
3. Map SDK/domain errors into internal error taxonomy.
4. Capture job_id and business context in your tracing system.

SDK Hardening Checklist

• Add per-call timeout defaults and circuit breaking.
• Track SDK version in logs for post-incident debugging.
• Test SDK upgrade in staging with archived production payloads.
• Implement fallback strategy by model and output format.

Error Recovery Flow

1. Classify error as retriable vs non-retriable.
2. Apply retry policy with capped attempts.
3. Escalate with full diagnostic context after budget exhausted.

When to Use Error Handling

Error Handling belongs to the SDK Reference section and covers implement robust sdk-level error handling and retries.

The page is written for developers and operators who need predictable video background removal behavior in production, not just a one-off demo request.

• Use Error Handling when wrapping the SDK in application services, queue workers, or automation scripts.
• Keep SDK calls server-side so API keys are never exposed in browser code.
• Add typed request validation around SDK inputs before passing user-provided files, URLs, or composition data.

Implementation Notes

Before you promote this workflow, test it with at least one short clip, one longer clip, and one visually difficult clip from your actual product or customer segment.

For support and debugging, persist the original input reference, selected model, output format, credit usage, and final job status alongside your internal user or project id.

• Do not instantiate SDK clients repeatedly inside tight loops when one process-level client is enough.
• Do not expose SDK calls that include secret keys from client-side routes.
• Do not upgrade SDK versions without replaying archived payload fixtures in staging.

Related Documentation

FAQ