Invalid_recurring_rule error when updating wallet via API

Calls to PUT /api/v1/wallets/{id} (and POST /api/v1/wallets) can return invalid_recurring_rule on the recurring_transaction_rules field. This is a catch-all validation error for the rule object, so the field at fault varies. The most frequent cause is a rule-level expiration_at that is not in the future.

What triggers the error

Any of these in a rule returns invalid_recurring_rule:

• expiration_at not strictly in the future, the most common case (see below)

• trigger missing or invalid, it must be interval with a valid interval, or threshold with a numeric threshold_credits

• interval not one of weekly, monthly, quarterly, yearly, semiannual

• method: target without a valid target_ongoing_balance

• paid_credits, granted_credits, or threshold_credits that are not valid decimals

• paid_credits exceeding the wallet's configured top-up limits

• transaction_metadata that is malformed

Sending more than one rule is a separate error, invalid_number_of_recurring_rules.

The expiration_at case

The rule's expiration_at must be strictly greater than the server's current time when Lago processes the request. A timestamp equal to "now" is rejected, so a value generated client-side (for example with time.Now() in Go) can fail by the time it is evaluated, since request and processing time push it to or before the current moment. Use a clearly future timestamp with an explicit timezone offset (Z or +00:00), or omit expiration_at if the rule should not expire.

Note that this article covers the rule-level expiration_at. The wallet has its own top-level expiration_at field, and a past value there returns a different error, invalid_date.

This article reflects guidance drawn from customer case resolutions. It is not officially supported documentation and may not apply to all situations.