New version 0.13.0!



Using APIs

Good practices when using APIs

When invoking APIs for task execution, adhere to the following best practices to ensure smooth handling of all situations:

  • Limit yourself to one API call per task execution. This ensures that in case of errors, only the failing API call will be retried.
  • By default, Infinitic considers the task completed when the service's method returns. Therefore, ensure that the underlying work can be executed synchronously during the API call. If not, for example for long-running tasks, use delegated tasks.
  • When your API permits an idempotency key, utilize Task.taskId.
  • Avoid catching technical errors within your code. If an API fails to respond correctly, ensure that exceptions are thrown. Infinitic will catch them and schedule task retries based on the retry policy defined.
  • In cases where an API call completes but the task can not be performed due to business-related issues (e.g., insufficient funds in a bank account), handle these errors by returning to the workflow a code indicating the specific situation. This allows for proper handling within the workflow logic. For this reason, we recommend encapsulating the return value within an object that can also describe any business issues encountered during task execution.


The following demonstrate how to use an external SDK, here Stripe, to code tasks. Here we consider a very simple Stripe service with only one charge method:

where PaymentIntentResult is a custom serializable class similar to Result<PaymentIntent>. Here is an implementation example of this service:

The Stripe SDK automatically converts errors into Exceptions. But most APIs don't. In that case it's also necessary to verify the HTTP status and raise exceptions manually (usually for error codes greater than or equal to 500). This practice ensures that a technical error prompts a retry.

Service Syntax