Error Handling

Stop infinite retries with Terminal Errors.

Restate handles retries for failed invocations.

Check out the Error Handling guide to learn more about how Restate handles transient errors, terminal errors, retries, and timeouts.

Retry strategies

By default, Restate does infinite retries with an exponential backoff strategy.

Check out the error handling guide to learn how to customize this.

Terminal Errors

For failures for which you do not want retries, but instead want the invocation to end and the error message to be propagated back to the caller, you can throw a terminal error.

You can throw a TerminalError with an optional HTTP status code and a message anywhere in your handler, as follows:

throw new TerminalError("Something went wrong.", { errorCode: 500 });

You can catch terminal errors, and build your control flow around it.

When you throw a terminal error, you might need to undo the actions you did earlier in your handler to make sure that your system remains in a consistent state. Have a look at our sagas guide to learn more.

Retryable errors with custom delay

Use RetryableError to signal that Restate should retry with a specific delay. This is useful when interacting with external APIs that return a Retry-After header.

RetryableError is primarily designed for use inside ctx.run blocks:

await ctx.run("call API", async () => {
    const res = await fetch("https://api.example.com/data");
    if (!res.ok) {
        const retryAfter = res.headers.get("Retry-After");
        throw new RetryableError("Rate limited", {
            retryAfter: { seconds: Number(retryAfter ?? 30) },
        });
    }
    return res.json();
}, { maxRetryAttempts: 10 });

You can also wrap an existing error using the RetryableError.from helper:

throw RetryableError.from(cause, {
    retryAfter: { seconds: 30 },
});

Unlike TerminalError which stops retries permanently, RetryableError tells Restate to retry after the specified delay. You can combine it with maxRetryAttempts and maxRetryDuration in the run options.

Pausing invocations with PauseError

Beyond retry policies, you can explicitly pause an invocation from within a ctx.run closure using PauseError. A paused invocation stops retrying and stays in the paused state until you manually resume it.

Use this when you want to halt processing until a human or operator resolves an issue:

import * as restate from "@restatedev/restate-sdk";

await ctx.run("charge-card", async () => {
  if (!paymentProviderConfigured()) {
    throw new restate.PauseError("Payment provider not configured yet");
  }
  // ... proceed with charging
});

When the condition is resolved, resume the invocation from the UI or CLI.

PauseError requires restate-server 1.7 with RESTATE_EXPERIMENTAL_ENABLE_PROTOCOL_V7=true enabled.

Mapping errors to TerminalError

If you’re using external libraries (e.g., for validation), you might want to automatically convert certain error types into terminal errors.

You can do this using the asTerminalError option in your service configuration.

For example, to fail with TerminalError for each MyValidationError, do the following:

class MyValidationError extends Error {}

const greeter = restate.service({
  name: "greeter",
  handlers: {
    greet: async (ctx: restate.Context, name: string) => {
      if (name.length === 0) {
        throw new MyValidationError("Length too short");
      }
      return `Hello ${name}`;
    },
  },
  options: {
    asTerminalError: (err) => {
      if (err instanceof MyValidationError) {
        // My validation error is terminal
        return new restate.TerminalError(err.message, { errorCode: 400 });
      }
    },
  },
});