Skip to main content

The error body

Every non-2xx response has the same body, and a Request-Id header to quote when you report a problem:

details you will see

details is left out when it would be empty. The trigger webhook’s rejections, invalid_body and bad_signature, also carry details.deliveryId. A code your SDK version does not know is kept as received.

In the SDKs

An error event that ends a stream raises the same PaddockError, with the HTTP status of its code.

Automatic retries

The SDKs retry idempotent requests (GET, PUT, DELETE) after a connection error, a timeout, or a 5xx, up to 2 times by default with capped exponential backoff and jitter. Set maxRetries (max_retries in Python, MaxRetries in Go) to change it, 0 to turn it off. A POST is never retried automatically, because it may have succeeded before the connection failed. After a failed send, look for the message in the session’s events before sending it again. Streams reconnect on their own; see Streaming.

Turn errors

A turn that fails does not fail any request: it ends with status: "failed" and an error on the turn and its turn.ended event, and the session shows it as lastError while it is retrying or failed. Unless the table says otherwise, a failed turn is retried up to two more times over the same messages, 10 seconds and then 60 seconds later; the retry’s attempt is one higher. When the agent gives up, the session is failed and the waiting messages are held: the next message you send starts a turn that includes them. Messages sent while a retry is planned start a turn at once.