Security
Retry and Idempotency
Handle duplicate attempts, concurrent requests, and transient failures safely.
Required headers
For canonical transaction ingestion, send x-api-key and idempotency-key. Keep the transaction UUID, idempotency key, and payload unchanged when retrying the same event. Use a new UUID and key for a different event.
Cached responses
Completed responses are cached for 24 hours, scoped to your organization and idempotency key. A retry with that key during this window returns the cached response without evaluating the transaction again.
The key identifies the event. Do not reuse it for a changed amount, party, or other payload field. The cache does not compare payloads before returning an existing response.
After the cache expires, do not assume the original decision will be replayed. Reconcile the existing transaction before submitting it again.
Concurrent requests
If an attempt with the same key is still processing, the API returns HTTP 409 with the response below. Wait, then retry the same event with its original UUID, key, and payload. Other 409 responses may represent business conflicts and require a correction instead of a retry.
{
"error": "Conflict",
"message": "Concurrent request is already being processed."
}Retry policy
Retry with a bounded policy
- Retry network timeouts and transient 5xx responses using the original UUID, key, and payload. A timeout does not prove that processing failed.
- Use exponential backoff with jitter and a maximum number of attempts.
- For HTTP 429, wait before retrying. Honor Retry-After when present. The ingestion rate-limit response does not currently guarantee that header.
- Stop after the retry budget and reconcile the transaction or contact support. Do not create a new event merely to bypass a failure.
Correct these errors before retrying
- HTTP 400: correct the payload or required headers.
- HTTP 401: check the API key and environment.
- HTTP 403: check organization access, source IP, and enabled capabilities.
- HTTP 409: inspect the message; only the concurrent-processing response described above is a retry signal.
Safe troubleshooting
Record the transaction UUID, idempotency key, HTTP status, timestamp, and redacted error details. Never log API keys, session cookies, or raw personal data.