API Connector Delivery, Retry, and Failure Handling

Connection pooling

Detect reuses a single shared pool of HTTP connections for all API connector traffic, instead of opening a new connection for every event. Connections negotiate HTTP/2 where the remote endpoint supports it, and fall back to HTTP/1.1 otherwise.

Timeouts

  • Connection timeout (api.connection.timeout, default 5 seconds): the maximum time the client will wait to establish a network connection with the target server. This happens during the initial TCP three-way handshake (and TLS handshake if using HTTPS). If the remote host does not respond in time, the attempt fails without retry.
  • Read timeout (api.socket.timeout, default 10 seconds): the maximum period of inactivity allowed between two consecutive data packets after a connection is established. This applies to responses from the target server and to the token exchange for bearer authentication. The timer resets each time data arrives, so it limits idle time, not the total request duration. For example, with a 5-second read timeout, a response that arrives in three packets spaced 4 seconds apart completes successfully after 12 seconds. If the server sends no data for longer than the timeout, the client throws a SocketTimeoutException.

Retries

Transient failures are retried automatically using exponential backoff with jitter (randomized delay), up to a default of 3 attempts. The following responses are considered transient and are retried:

  • 5xx server errors
  • HTTP 429 (Too Many Requests)
  • Connection and read timeouts
  • Connection refused and DNS resolution failures

The following responses are terminal and are not retried:

  • 4xx client errors other than 401, for example 400, 403, 404, and 422. These indicate the request itself is malformed or rejected, so retrying will not help.

Bearer token handling

When the API configuration uses bearer token authentication, Detect fetches an access token once and reuses it for subsequent events until it expires, rather than requesting a new token for every event. If multiple events need a token at the same time, Detect shares a single in-flight token request instead of making redundant calls.

If a request returns HTTP 401 (Unauthorized), Detect discards the cached token, fetches a new one, and retries the request once. If the retry also returns 401, the failure is treated as terminal, since this indicates the configured credentials are incorrect or have been revoked.

Idempotency and duplicate delivery

Every request includes a unique Idempotency-Key header. Delivery is at-least-once, so the downstream system may occasionally receive the same event more than once, for example if a response is lost after the remote system has already processed the request. Downstream systems should use the Idempotency-Key value to detect and ignore duplicates.

Messages that exhaust retries

If a message still fails after all retry attempts, it is not delivered and the delivery outcome is recorded for audit purposes.