API Calls with Retries

Call external APIs from workflows with automatic retry policies. Grove activities handle transient failures with configurable backoff, max attempts, and timeout.

Prerequisites: Workflows, Activities, Services. What you'll learn: How to call external APIs with retry policies and error handling.

The Pattern

Declare a service for the external API
Create an activity that fetches from the service
Configure a retry_policy for transient failures
Wire it into a workflow

Service Declaration

service stripe v1 {
  credentials {
    api_key: "stripe_secret_key"
  }

  auth {
    protocol bearer
    source credentials.api_key
  }

  operation create_charge {
    amount: Int
    currency: String
    customer_id: String
  }

  operation get_charge {
    charge_id: String
  }
}

Activity with Retry

activity charge_payment v1 {
  data charge {
    fetch stripe.create_charge {
      amount: input.amount
      currency: input.currency
      customer_id: input.customer_id
    }
  }

  apply(input: ChargeInput) -> ChargeResult {
    return {
      charge_id: charge.id,
      status: charge.status
    }
  }

  retry_policy {
    max_attempts: 3
    backoff: 2s
    max_backoff: 30s
    timeout: 60s
  }
}

Retry Policy Fields

Field	Default	Description
`max_attempts`	1	Maximum number of attempts (including the first)
`backoff`	1s	Initial backoff duration between retries
`max_backoff`	--	Maximum backoff duration (caps exponential growth)
`timeout`	--	Per-attempt timeout

Backoff is exponential: first retry waits backoff, second waits backoff * 2, and so on up to max_backoff.

Workflow Integration

workflow process_payment v1 {
  node validate = validate_payment v1
  node charge = charge_payment v1
  node notify = send_receipt v1

  edge validate -> charge
  edge charge -> notify
}