Idempotency, Retries & Error Handling

ResultFly expects clients to retry safely. Idempotency is what makes those retries correct.

1. CDP Event Ingestion

CDP ingest deduplicates events by:


(tenant, source, externalEventId)

If your system is not sure whether a request succeeded, resend the exact same event with the same externalEventId.

Expected behavior:

first delivery is accepted
repeated delivery with the same event key is treated as a duplicate
business effects are not applied twice

2. Runtime Mutations

Runtime variable mutations should also be retry-safe.

Provide a stable mutation identifier when calling runtime variable mutation operations. Reusing the same identifier should return the original outcome instead of applying the same mutation twice.

3. Safe Retry Rules

Safe to retry with the same idempotency key:

network timeout
connection reset
429 Too Many Requests
5xx response

Do not retry unchanged requests after:

401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
422 Unprocessable Entity

Those errors usually mean credentials, scope, identifiers, or payload structure must be corrected first.

4. Error Codes

Code	Meaning	Client action
`400 Bad Request`	Payload malformed or unsupported request shape.	Fix the request before retrying.
`401 Unauthorized`	Invalid API key or JWT.	Refresh or replace credentials.
`403 Forbidden`	Caller lacks permission for this operation.	Use a correctly scoped credential.
`404 Not Found`	Referenced resource or runtime context does not exist.	Verify identifiers and context.
`409 Conflict`	Duplicate or conflicting operation.	Inspect the conflict before retrying.
`422 Unprocessable Entity`	Validation failed on a known field.	Correct the payload and resend.
`429 Too Many Requests`	Rate limit exceeded.	Back off and retry later.
`5xx Server Error`	Transient platform failure.	Retry with the same idempotency key.

5. Recommendation

Always generate idempotency values in the caller’s own system of record.

For CDP ingest, externalEventId should represent the real business fact, not an HTTP attempt. That is what keeps retries, replays, and batch recovery safe.