Partial/Failed Response Policy

Configure how to charge users for partial or failed API responses.

Overview

Sometimes API calls may return partial responses (incomplete) or fail entirely. The Partial/Failed Response Policy allows you to control how users are charged in these scenarios.

Configuration Settings

Partial Response Discount

Type: Decimal (0.0 to 1.0)
Default: 0.5 (50%)
Description: Discount percentage applied when API returns a partial response.

How it works:

1.0 = Charge full price (no discount)
0.5 = Charge 50% (50% discount)
0.0 = Free (100% discount)

Example: If a response costs $1.00 and Partial Response Discount = 0.5:

User is charged: $1.00 × 0.5 = $0.50

Failed Response Charge

Type: Decimal (0.0 to 1.0)
Default: 0.0 (Free)
Description: Charge percentage applied when API call fails.

How it works:

0.0 = Free (no charge for failed responses)
0.5 = Charge 50% (partial charge)
1.0 = Charge full price (not recommended)

Example: If a response costs $1.00 and Failed Response Charge = 0.0:

User is charged: $1.00 × 0.0 = $0.00 (Free)

Response Status Types

Success

Status: Complete response received
Charge: Full price (no discount)

Partial

Status: Incomplete response (e.g., API timeout, partial data)
Charge: Retail Price × Partial Response Discount
Example: If discount = 0.5, user pays 50% of the original price

Failed

Status: API call failed (e.g., network error, API error)
Charge: Retail Price × Failed Response Charge
Example: If charge = 0.0, user pays nothing (free)

Example Scenarios

Scenario 1: Conservative (Protect Users)

Partial Response Discount: 0.3 (70% discount)
Failed Response Charge: 0.0 (Free)

Result: Users pay very little for incomplete/failed responses, protecting user experience.

Scenario 2: Balanced (Default)

Partial Response Discount: 0.5 (50% discount)
Failed Response Charge: 0.0 (Free)

Result: Users pay half price for partial responses, nothing for failures. Good balance between UX and cost recovery.

Scenario 3: Cost Recovery

Partial Response Discount: 0.8 (20% discount)
Failed Response Charge: 0.2 (20% charge)

Result: Users pay most of the cost even for partial/failed responses. Use only if API costs are very high.

Best Practices

Failed Responses Should Be Free: Set Failed Response Charge = 0.0 to maintain good user experience. Users shouldn't pay for failures.
Partial Responses: Consider your API costs:
- High API costs → Higher discount (0.3-0.5)
- Low API costs → Lower discount (0.7-0.9)
Monitor Failure Rates: Track partial/failed response rates to optimize your settings.
User Experience First: Prioritize user experience over cost recovery for failed responses.

Access Settings

Navigate to Settings > Params in your Hero dashboard, then go to the Reseller tab to configure these settings.