Errors and retries

What each error means, what the client retries for you, and keys that survive your own restarts.

When things go wrong

Everything thrown is a JwtsonError with code, status and requestId, and a message written for people.

Error	Means
`ValidationError`	The request is wrong. `details` lists the fields, and the message includes them
`AuthenticationError`	The token is missing or expired
`PermissionError`	The token doesn't hold the grant this needs
`NotFoundError`	It doesn't exist, or you can't see it
`ConflictError`	Someone changed it first
`RateLimitError`	Too many requests, even after retrying. `retryAfterMs` says how long to wait
`ServerError`, `ConnectionError`	Still failing after retrying
`ConfigurationError`	Setup is missing something. The message says what to pass
`RunFailedError`, `RunCanceledError`, `RunTimedOutError`	The run ended without an answer. `failure` has the reason. `RunTimedOutError` is a `RunFailedError` whose reason is `time_limit_exceeded`
`WaitTimeoutError`	`timeoutMs` passed. The run itself keeps going

A read that fails in passing is sent again, and so is a write, because every write carries an idempotency key and the API won't apply one twice. A refusal is never retried. Set maxRetries to change the number of tries, or 0 to turn this off.

The key lives for one call. If your own process can restart and repeat the call, pass your own: agent.start(input, { idempotencyKey: order.id }). Every change to a run takes one too: run.cancel(), run.resume(), run.say(), wait.answer() and approval.approve().

To stop a run only as you saw it, give its revision: run.cancel({ revision, idempotencyKey }), with the detail.revision you read when you decided. If it moved on, you get a ConflictError and nothing changes. Without one, cancel() stops it as it is now.

From the @jwtson/sdk README, as the code stands.