Resolved

OpenRouter API 402 credit exhaustion causes excessive retries

Python
API
Error Handling
Async
OpenAI
FastAPI
Debugging
Retry Logic

HTTP 402 errors from OpenRouter API trigger 13 unnecessary retries over 2+ minutes | Generic retry logic treats credit exhaustion as transient error | Solution implements immediate detection and graceful exit

Issue

The OpenRouter API integration in the video generation pipeline wasted processing time and resources by retrying non-recoverable HTTP 402 credit exhaustion errors. The system performed 13 retries over ~2+ minutes before failing, despite the error requiring manual credit top-up. This resulted in:

  • Wasted time: Delayed script execution and redundant retries.
  • Log spam: Excessive retry messages clogging logs.
  • Poor user feedback: Unclear error messages and no guidance for resolving credit issues.

Culprit

The retry logic in the generator and orchestrator components treated all errors uniformly, including permanent credit exhaustion errors. Specifically:

  1. No error differentiation: HTTP 402 errors (credit limits) were retried like transient issues.
  2. Layered retries: Both the generator (3 retries) and orchestrator (10 retries) attempted recovery, compounding delays.
  3. Missing early detection: The system lacked logic to immediately detect and handle credit exhaustion errors.

Solution

Three-Tiered Fast-Fail Mechanism

  1. Custom Exception Class: Introduced CreditExhaustedError to explicitly handle credit exhaustion cases.
  2. Early Detection: Added logic to detect HTTP 402 or credit-related errors in the retry loop and raise CreditExhaustedError immediately.
  3. Orchestrator Bypass: Modified the orchestrator to skip all retries for credit errors and provide clear actionable feedback, including a direct link to add credits.

Results

  • Before: 13 retries, ~2+ minutes wasted, unclear error messages.
  • After: Immediate detection (0 retries), clear feedback with a direct link to add credits, graceful termination.

User Impact

  • Efficiency: Users can re-run scripts immediately after adding credits without manual intervention.
  • Idempotency: Completed URLs are skipped to avoid reprocessing.

The solution ensures efficient handling of credit exhaustion errors while providing clear guidance for resolution.