Idempotency, Retries & Error Handling

1. Idempotency

External events. Deduplicated by (tenant, source, external_event_id). Resend the same event if the response is unclear; ResultFly acknowledges duplicates without reapplying business effects.
State mutations. Provide mutation_id (or the Idempotency-Key header, depending on SDK) when calling POST /v1/runtime/state:mutate. Reusing the same key returns the original outcome, ensuring repeated requests do not alter State twice.

Safe to retry: network timeouts, 5xx responses, and 429 Too Many Requests. Use exponential backoff with jitter (for example, 1s, 2s, 4s…) and stop after a reasonable number of attempts.
Do not retry: 4xx validation errors (400, 401, 403, 404, 409, 422) until the payload or credentials are fixed. Repeating these requests will produce the same error.
Always include idempotency identifiers so that retried calls remain safe when they eventually succeed.

Code	Meaning	Client Action
400 Bad Request	Payload malformed or refers to undeclared variables/system fields.	Fix payload and resend.
401 Unauthorized	Authentication failure (invalid API key/JWT).	Refresh credentials; do not retry until fixed.
403 Forbidden	Credentials lack scope for the requested campaign or operation.	Request appropriate access or use different credentials.
404 Not Found	Resource, identity, or campaign does not exist for this request.	Verify identifiers before retrying.
409 Conflict	Duplicate event/state mutation detected or conflicting state.	Investigate conflict; only retry with corrected identifiers.
422 Unprocessable Entity	Validation error on input fields.	Correct data and resend.
429 Too Many Requests	Rate limit exceeded.	Apply backoff and retry later.
5xx Server Error	Transient platform issue.	Retry with backoff; idempotency ensures safe replays.