Reliable delivery
Buffer telemetry durably before sending it. Your integration should tolerate a lost connection, rate limiting, temporary API failures and a lost acceptance response without duplicating payment attempts.
Batch within one institution
Send an events array with one to 1,000 events through POST /v1/telemetry/batches. Every event must belong to the same credential's institution, organisation and environment. The JSON request must fit within 1 MiB; the byte limit applies even when there are fewer than 1,000 events.
Split larger payloads into smaller batches while preserving the original event IDs and content. Each event ID may appear only once within a batch.
Treat acceptance and processing separately
202 Accepted confirms durable acceptance for asynchronous processing. Save the returned request_id, batch_id, accepted_event_count, duplicate_event_count and accepted_at. It does not establish that the outcome has already been processed.
The first processed outcome establishes the connected milestone. Check integration status and last activity with your Teria administrator. Silence by itself does not mean the credential is disconnected.
Retry without changing the observation
| Result | Action |
|---|---|
| Connection failure or lost response | Retry the same immutable events. |
429 |
Use exponential backoff with jitter; honor Retry-After when present. |
Temporary 500 or 503 |
Retry the same immutable events with backoff and jitter. |
400, 401, 403 or 409 |
Resolve the stated problem before resending. Keep buffered events. |
413 |
Split into smaller batches without changing events. |
Teria validates the whole batch, checks scope and detects immutable-content conflicts before enqueueing events. Such validation failures reject the whole batch. A temporary transport or server failure can still happen after some events have been queued, so a non-202 response is not proof that no event reached processing. Retry the original events safely.
For V3, an identical event ID and content is a duplicate, scoped to the organisation, institution and environment. The same ID with changed event content causes 409 Conflict. Batch metadata and JSON property ordering do not turn an event into a new observation. Preserve occurrence times, identifiers and measured values on retry.
If a later result arrives, create a new event ID with the same attempt ID. Do not generate a new ID solely to bypass a conflict.
Respect the event-age limit
V3 accepts occurrence times up to seven days old and up to five minutes in the future. Synchronize your integration's clock. Keep the original occurrence time when recovering a buffered observation; changing it would falsify the observation.
The age check also applies to retries of previously accepted events. Monitor buffer age, and contact your Teria administrator before an outage causes events to exceed seven days. Retain aged events for explicit reconciliation rather than silently discarding them or resending with a fabricated current timestamp.
Pause, revocation and recovery
Paused access keeps the credential available for use after access resumes. A revoked or retired credential needs replacement. Already accepted telemetry continues processing after a pause or revocation. Resume your buffered feed once valid access is restored, using unchanged event identities and timestamps.
Do not treat telemetry acceptance as authorization to initiate a payment. Your organisation remains responsible for routing and payment execution.