Merge pull request #1055 from segmentio/function-retry-error

Update function docs for RetryError

Author: chriso

src/connections/functions/destination-functions.md

@@ -86,11 +86,12 @@ To change which type of event the handler listens to, you can rename it to the n
 
 A function's execution is considered successful if it finishes without any errors. You can also `throw` an error to indicate a failure on purpose. You can use these errors to validate event data before processing it, to ensure your function works as expected.
 
-There are three pre-defined error types that you can `throw` to indicate that the function ran as expected, but that data could not be delivered:
+You can `throw` the following pre-defined error types to indicate that the function ran as expected, but that data could not be delivered:
 
 - `EventNotSupported`
 - `InvalidEventPayload`
 - `ValidationError`
+- `RetryError`
 
 The examples show basic uses of these error types.
 
@@ -110,6 +111,27 @@ async function onPage(event) {
 async function onAlias(event) {
   throw new EventNotSupported('Alias event is not supported')
 }
+
+async function onTrack(event) {
+  let res
+  try {
+    res = await fetch('http://example-service.com/api', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ event })
+    })
+  } catch (err) {
+    // Retry on connection error
+    throw new RetryError(err.message)
+  }
+  if (res.status >= 500 || res.status === 429) {
+    // Retry on 5xx and 429s (ratelimits)
+    throw new RetryError(`HTTP Status ${res.status}`)
+  }
+}
+
 ```
 If you do not supply a function for an event type, Segment throws an `EventNotSupported` error by default.
 
@@ -186,8 +208,9 @@ A function can throw errors, or Segment might encounter errors while invoking yo
 - **Invalid Settings** - A configuration error prevented Segment from executing your code. If this error persists for more than an hour, [contact Segment Support](https://segment.com/help/contact/).
 - **Message Rejected** - Your code threw `InvalidEventPayload` or `ValidationError` due to invalid input.
 - **Unsupported Event Type** - Your code does not implement a specific event type (`onTrack()`, etc.) or threw a `EventNotSupported` error.
+- **Retry** - Your code threw `RetryError` indicating that the function should be retried.
 
-When these errors occur, Segment does not attempt to send that event to your destination function again.
+Segment only attempts to send the event to your destination function again if a **Retry** error occurs.
 
 ### Destination functions logs
 

src/connections/functions/source-functions.md

@@ -350,8 +350,9 @@ async function onRequest(request, settings) {
 - **Invalid Settings**: A configuration error prevented Segment from executing your code. If this error persists for more than an hour, [contact Segment Support](https://segment.com/help/contact/).
 - **Message Rejected**: Your code threw `InvalidEventPayload` or `ValidationError` due to invalid input.
 - **Unsupported Event Type**: Your code does not implement a specific event type (`onTrack()`, etc.) or threw a `EventNotSupported` error.
+- **Retry** - Your code threw `RetryError` indicating that the function should be retried.
 
-These errors are not retried.
+Segment only attempts to run your source function again if a **Retry** error occurs.
 
 ## Managing source functions