Errors And Retries

The SDK throws RooaakError for non-2xx responses.

RooaakError includes:

• code
• status
• details

Retry behavior

Retries use exponential backoff with jitter and apply to retryable HTTP statuses (429, 5xx) only when the request is safe to retry.

Safe to retry:

• GET requests (idempotent)
• POST requests where you provide an idempotency key

Not safe to retry automatically:

• POST requests without idempotency keys (could create duplicates)

Practical guidance

• Always set an idempotency key for messages.send(...) if your infrastructure might retry requests.
• If you build your own retry wrapper around agents.start(...), prefer polling agents.get(...) for status === "running" rather than retrying rapidly.