# recurly transaction declined "gateway error" on first renewal

## TL;DR
The first renewal failed with a generic gateway error, which usually means the card or the gateway hiccuped rather than the customer doing anything wrong. Retry once after a short delay, then fall into your dunning flow with customer outreach. If gateway errors cluster, check Recurly status before assuming it is the cards.

```text
recurly transaction declined "gateway error" on first renewal
```

## Steps

1. Read the full transaction detail; gateway error is a wrapper, and the underlying code often says more. Success check: you have the sub-code or raw gateway message.
2. Retry the charge once after a short delay; transient gateway errors clear on their own. Success check: the retry either succeeds or returns a more specific decline.
3. If the retry fails, start dunning: notify the customer and schedule the next attempt per your retry policy. Success check: the customer knows a payment failed and what to do.
4. Watch for clusters: several gateway errors in a short window point at the gateway, not the customers. Success check: you checked the status page before blaming cards.
5. For repeat first-renewal failures on the same account, prompt a payment method update before the next retry. Success check: the next attempt runs against a fresh method.

## When this applies

- A Recurly subscription's first renewal is declined with a gateway error.
- The signup charge succeeded but the renewal failed.
- You need a retry policy for generic gateway declines.

## When it doesn't

- Declines with specific reasons like insufficient funds; follow the reason.
- Initial signup charges failing; that is a checkout problem.
- Gateway-wide outages; those are status-page incidents.

## Tool + version compatibility

Recurly transactions, subscriptions, and dunning (all current API versions).

### "recurly gateway error on renewal"
Read the sub-code, retry once, then dunning.

### "recurly first renewal failed"
Signup worked so the method was valid once; treat it as retryable first.

### "recurly transaction declined gateway error"
Cluster check first: one card or the whole gateway.

## Why it happens

First renewals are the riskiest charge in a subscription's life: the card that worked at signup may have expired, hit a limit, or been replaced, and the gateway wraps many of these as a generic error. A single retry catches the transient cases; everything else is dunning. Agents that retry aggressively turn one failed renewal into a string of declines that can flag the card.

## Edge cases / pitfalls

- Space retries per your dunning schedule; rapid-fire retries look like fraud to issuers.
- First-renewal failure rate is a business metric; track it separately from later renewals.
- If the gateway error persists across many customers, pause retries and check gateway status.
- Never retry a renewal more times than your dunning policy allows; the policy is the guardrail.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_tA7i2R-GTB3ZxBdVLLGdwA