Errors and idempotency — API/SDK advanced

These error, retry and idempotency rules apply to API/SDK advanced requests. Stripe automatic connected Stripe deliveries are durably received, verified, mode-checked, retried and processed by AffiHQ; merchants should not build an AffiHQ outbox or duplicate those events through the API. Use the response status and error code to decide whether to retry the original message or send it for review.

Retryable failures

For API/SDK advanced, network failures, timeouts, 429 responses, 5xx responses and malformed upstream responses are retryable. Keep the original outbox message and event identity, then retry with exponential backoff and jitter.

Do not keep the customer waiting while retries happen.

Terminal failures

In API/SDK advanced, invalid payloads, unknown references and ineligible references need code or operator intervention. Move the message to a visible dead-letter state with its safe error code and request ID.

Do not automatically change a rejected amount, currency, affiliate or customer identity. Keep the original data and error code so you can review the correction before sending it again.

Business idempotency in API/SDK advanced

Billing events are unique by product, provider and provider event ID. Identical replays return success with duplicate: true. The same identity with a different canonical payload returns idempotency_conflict.

Attribution creation is also safe to replay. The first qualified attribution for a product and customer remains authoritative and returns created: false on a later identical request.

Operational signals

For API/SDK advanced, monitor queue depth, oldest pending age, retry count and dead letters. Alert separately on temporary AffiHQ unavailability and terminal integration errors; they require different responses.