What is a retry?
A retry is trying the same thing again after it failed, usually after a short wait, in case the problem was only temporary.
In plain words
If you call a friend and the line is busy, you wait a minute and call again. That is a retry. Most problems on the internet are like this: a brief hiccup that is gone moments later.
Software retries all the time, and a good one is polite about it. It waits a little longer after each failure, which is often called backing off. That stops a struggling service from being flooded with repeat requests.
Retrying is only safe when doing the thing twice cannot cause harm. Calling a friend twice is harmless. Sending a customer the same message twice is not.
So retries go hand in hand with a way to mark a request as the same one, so that it counts only once.
And some failures should not be retried at all. If you are told you reached a limit, trying again straight away will not help. Waiting as long as you are told will.
How it works in Spaces
Failed webhook deliveries are retried with backoff for about a day. After 50 events fail in a row, that webhook turns off.
When a request is refused with 429, the answer says retry_after_seconds, and nothing was sent. Wait that long and retry with the same Idempotency-Key. When a channel is briefly unavailable, nothing was sent, and you can try later.
Related terms
- Safe to retry: Something is safe to retry, or idempotent, when doing it twice has the same result as doing it once, so a repeat never sends a second copy.
- Rate limit: A rate limit is a cap on how much can be done in a set time, such as messages in a day, which keeps a service fair and an account safe.
- Webhook: A webhook is a message one service sends automatically to another's web address the moment something happens, such as a new customer message arriving.
- Webhook signature: A webhook signature is a stamp added to each message a service sends to your web address, so you can check it really came from them and was not changed on the way.
FAQ
Will a retry send my message twice?
Not when the same Idempotency-Key is used. A repeat is recognised as the same send.
How soon should my agent retry?
After the wait the answer asks for. A 429 refusal carries the number of seconds.
What if my web address is down when an event is sent?
Spaces keeps retrying with backoff for about a day, and you can catch up from the event stream afterwards.
Why did a webhook turn itself off?
After 50 events fail in a row, Spaces stops sending to it. Fix the address and create it again.
Useful next: Sending limits, Errors explained, API reference. Every term: the glossary.