Billionmail/BillionMail · error

lipsync API error %d: %s

Error message

lipsync API error %d: %s

What it means

SubmitLipSync returns this when the lipsync provider responds with any status other than 200 or 201. The response body is read and embedded verbatim in the message, so the provider's own error text (auth errors, validation messages, quota info) is included after 'lipsync API error <code>: '. This is a server-side rejection, not a transport failure.

Source

Thrown at core/internal/service/video_gen/lipsync.go:125

		VideoURL:       videoURL,
		SynergizeAudio: true,
	}

	httpReq, err := BuildLipSyncRequest(cfg, req)
	if err != nil {
		return "", err
	}
	httpReq = httpReq.WithContext(ctx)

	resp, err := cfg.doHTTP(httpReq)
	if err != nil {
		return "", fmt.Errorf("lipsync API call: %w", err)
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK && resp.StatusCode != http.StatusCreated {
		body, _ := io.ReadAll(resp.Body)
		return "", fmt.Errorf("lipsync API error %d: %s", resp.StatusCode, string(body))
	}

	var result LipSyncResponse
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		return "", fmt.Errorf("decode lipsync response: %w", err)
	}
	return result.ID, nil
}

// CheckLipSyncStatus checks the status of a lip sync job.
func CheckLipSyncStatus(ctx context.Context, cfg LipSyncConfig, jobID string) (*LipSyncResponse, error) {
	httpReq, err := BuildLipSyncStatusRequest(cfg, jobID)
	if err != nil {
		return nil, err
	}
	httpReq = httpReq.WithContext(ctx)

	resp, err := cfg.doHTTP(httpReq)

View on GitHub (pinned to fc36c76c05)

Solutions

1. Read the embedded provider message after 'lipsync API error <code>: ' — it states the exact cause (auth, validation, quota)
2. For 401/403, rotate/verify the x-api-key value in your lipsync config/env
3. For 400/422, compare your request payload against the provider's current API docs (schema drift after version updates)
4. For 429/5xx, add retry with exponential backoff and rate limiting on submission volume
5. Check account credits/plan limits on the provider dashboard for 402/429

Example fix

// before
id, err := SubmitLipSync(ctx, cfg, ...) // error: lipsync API error 401: {"detail":"Invalid API key"}
// after
id, err := SubmitLipSync(ctx, cfg, ...)
if err != nil {
    var apiErr *LipSyncAPIError // wrap status+body in a typed error at the call site
    if errors.As(err, &apiErr) && apiErr.StatusCode == 401 {
        log.Error("lipsync auth failed: check LIPSYNC_API_KEY")
    }
}

// before calling
if strings.TrimSpace(cfg.APIKey) == "" {
    return fmt.Errorf("lipsync API key not configured")
}

func isLipSyncAPIError(err error) (status int, body string, ok bool) {
    var e *LipSyncAPIError
    if errors.As(err, &e) {
        return e.StatusCode, e.Body, true
    }
    return 0, "", false
}

id, err := SubmitLipSync(ctx, cfg, ...)
if err != nil {
    if status, body, ok := isLipSyncAPIError(err); ok {
        switch {
        case status == 401 || status == 403:
            // alert: invalid/rotated API key
        case status == 429:
            // backoff and retry later
        case status >= 500:
            // provider outage; retry with backoff
        default:
            // 4xx: log provider body for validation fix
        }
    }
    return err
}

When it happens

Trigger: Calling SubmitLipSync with an invalid/expired API key (401/403), malformed request body rejected by the provider (400/422), insufficient credits or quota (402/429), provider 5xx outage, or a provider API version change that altered the endpoint contract.

Common situations: API key rotated in provider dashboard but not updated in env/config; source/target asset URLs the provider cannot fetch; account out of credits; provider introduced new required field or deprecated an endpoint; rate limiting during bulk submissions.

Related errors

• create lipsync request: %w
• create status request: %w
• decode lipsync response: %w
• lipsync status API error %d: %s
• download lipsync video: %w

AI-assisted analysis of Billionmail/BillionMail@fc36c76c05 (2026-09-05). Data as JSON: /api/errors/2928ed18aa49f037. Report an issue: GitHub.