Skip to main content
An integration that works on a laptop and an integration that survives production differ in a handful of details: key hygiene, event identity, batch bounds, retry rules, and the signals you watch afterwards. This page covers the checks before launch and the runbooks for the three things that go wrong after it.

​
Before you launch

​
Credentials and environments

Key hygiene starts with one key per consumer:
  • Development, staging, and production senders each hold their own key. Those keys separate credentials, not data, because Reconify has no sandbox or test mode.
  • Senders hold write keys and readers hold read keys.
  • An admin key appears only where one service genuinely does both.
  • Every secret lives in a secret manager.
  • Each key has a recorded owner and a recorded service.
  • An exposed key gets rotated immediately.

​
Event identity

Identity is what makes a retry safe:
  • The source system supplies a stable event.id.
  • A retry reuses the same ID and the same payload.
  • Events without IDs count as unsafe to retry.
  • No ID is ever reused for different event content.
  • The reference stays identical across the events of one operation.

​
Batches and concurrency

The contract bounds a batch, and your sender bounds the traffic:
  • Each batch carries between 1 and 500 events.
  • The request body stays at or below 5 MiB, and each event at or below 256 KiB.
  • The sender bounds its concurrent requests.
  • Every batch result keeps its index through your handling code.

​
Retry behavior

Each failure has one correct response:
  • A 503 gets retried with exponential backoff and jitter.
  • Rejected items go back out only after the input is fixed.
  • An unchanged 400, 401, 403, 404, 409, 413, or 422 never gets retried.
  • A duplicate item result counts as successful delivery.
  • An idempotency_conflict counts as a data-integrity error that needs a human.

​
Observability

Five signals tell you the sender is healthy:
  • Every response’s X-Request-ID reaches your logs.
  • The counts of accepted, duplicate, and rejected results are tracked.
  • Events that stay in received or published are tracked.
  • Rising rejection, conflict, and 503 rates raise an alert.
  • Bearer tokens and raw financial payloads never reach your logs.

​
Data handling

Evidence is customer data everywhere it travels:
  • Financial data is redacted from logs and tickets.
  • Raw API responses stay out of external AI systems.
  • Access to member IDs and organization data is reviewed.
  • Your required retention and deletion policy is confirmed before live data flows.
The public API publishes no organization rate limit and makes no 429 or Retry-After commitment. Your own concurrency bound is the protection, and the SDK backs off on 503.

​
Rotate a key

Rotation happens without downtime when the replacement runs before the revocation.
1

Create the replacement

The new key carries the same least-privilege scope and a name that identifies the consuming service.
2

Deploy the replacement

The service picks it up through your secret manager. Neither key belongs in a command history, a deployment log, or a source-controlled environment file.
3

Confirm normal traffic

A read key proves itself against a protected GET route. A write key proves itself in the next normal production batch and its item results, which avoids creating a synthetic production event.
4

Revoke the old key

Revocation follows once every consumer uses the replacement. A 401 afterwards identifies the consumer you missed.

​
When processing is slow

Asynchronous evaluation normally finishes in seconds. When an event sits longer, six steps separate a delay from a delivery problem:
  1. The ingestion result for the item reads accepted or duplicate.
  2. A read by event ID shows whether it is received, published, processed, or failed.
  3. Reconify status shows any active incident.
  4. An accepted event never gets resent to push processing along.
  5. The event ID, request ID, route, and UTC timestamp go into your record.
  6. A state that has not advanced past the flow’s deadline justifies a redacted support packet.

​
When a provider degrades

Provider evidence and user evidence stay on separate paths: A user payment event stored as durable evidence while the provider tracker looks the transaction up, producing either normalized provider evidence, a pending retry, or a provider issue, then a corroborated outcome or a mismatch finding. A provider timeout, authentication failure, rate limit, or unmapped status is a provider issue, and Reconify converts none of them into a synthetic payment.failed event. The accepted user event stays exactly as it is, because provider checks are separate evidence rather than authority over it. The fix runs through the integration: its health reason in the dashboard, then the environment against the credential, then the replacement credential or corrected status mapping, then the optional test with a safe provider-side identifier. Later provider evidence lands on the same operation.

​
After launch

Four signals tell you whether the integration still behaves:
  • The ratio of accepted, duplicate, and rejected results. A rising rejection rate usually means a source system changed its contract.
  • Every idempotency_conflict, which points at the producer’s identity mapping.
  • Provider connection health, especially after credential, endpoint, or mapping changes.
  • The findings and evidence in the dashboard.
The changelog is worth a read before any SDK major version upgrade, and Troubleshooting carries the support packet template for anything that needs escalation.