​

Errors, retries, and limits

​

HTTP status handling

Error bodies are JSON and can include an error, code, validation details, or a structured acceptance result. Log the response body after removing personal data.

​

Retry policy

Retry:

• network timeouts
• connection failures
• 429
• temporary 5xx

Do not retry unchanged:

• 400
• 401
• 403
• most 404 responses

Use exponential backoff with jitter, for example 1, 2, 4, 8, and 16 seconds, and honor Retry-After when present.

​

Make retries safe

​

Ingest

Reuse the original externalId. A successful replay can return status: "idempotent_replay" with the existing lead ID.

​

Buyer delivery

Deduplicate incoming events by transactionId. Return 2xx for a transaction you already accepted.

​

Lifecycle callbacks

Reuse the same transaction reference and desired state. A response can indicate that the transition was already applied; treat that as success.

​

Rate limits

Limits vary by integration surface and may change to protect the service. Connect endpoint resolution is particularly guarded against repeated or guessed IDs. Design clients to:

• cache successful configuration lookups when appropriate
• avoid polling invalid IDs
• limit concurrency
• honor 429 and Retry-After
• stop after a bounded number of attempts

​

What to record

For each request, keep:

• timestamp
• environment
• endpoint family
• external ID or transaction ID
• HTTP status
• sanitized response code and message
• retry attempt number

Never log webhook secrets or full personal payloads.