Errors and limits
Error responses use application/problem+json. Keep the request_id when contacting your Teria administrator, along with the environment, response status and approximate time. Exclude credential secrets and personal data.
{
"type": "https://teria.dev/problems/invalid-telemetry-batch",
"title": "Invalid telemetry batch",
"status": 400,
"request_id": "609dc0cd-496e-416b-a639-422802b4def5",
"detail": "One or more event timestamps are outside the accepted range.",
"errors": [
{
"path": "/events/0/occurred_at",
"code": "event_time_out_of_range",
"message": "Events may be at most seven days old or five minutes in the future."
}
]
}
The errors list is present when field-level detail is available. Inspect each path, code and message; do not depend on exact human-readable wording.
Response guide
| Status | Meaning | Next step |
|---|---|---|
202 |
Durably accepted, possibly including identical duplicates. | Check counts; confirm processing separately. |
400 |
Invalid body, unsupported field, duplicate ID within a batch, unknown directory ID or invalid event time. | Correct the request. For an already observed event, preserve its immutable facts. |
401 |
Missing, invalid, revoked or retired credential. | Obtain valid credentials. |
403 |
Paused/disabled access or an optional scope assertion that does not match the credential. | Inspect the problem type and resolve access with your Teria administrator. |
409 |
A V3 event ID was reused with different content. | Reconcile the original observation. A genuinely later observation requires a new ID. |
413 |
Request exceeds 1 MiB. | Split it into smaller batches. |
429 |
Requests are rate limited. | Back off with jitter and honor Retry-After if supplied. |
500, 503 |
Temporary server or delivery failure. | Retry immutable events with backoff. Some events may already have been queued. |
For paused access, the problem type ends in telemetry-access-paused. Keep the buffer and resume once the administrator restores access. Invalid or revoked credentials return a generic authentication failure rather than revealing credential state to an unauthenticated caller.
V3 limits
| Limit | Value |
|---|---|
| Events in one batch | 1–1,000 |
| JSON request size | At most 1 MiB (1,048,576 bytes) |
| Oldest occurrence time | Seven days before acceptance |
| Furthest future occurrence time | Five minutes after acceptance |
| Organisation, institution, destination and switch identifiers | At most 64 characters; use the assigned identifiers |
| Transaction and attempt references | 1–128 characters |
| Response code | 1–32 characters when supplied |
| Credential rotation overlap | At most 24 hours |
| Automatic credential expiry | None |
The API reference is the complete source for field constraints. Throughput allowances may vary by sandbox setup; use backoff and confirm your planned request volume with Teria before running a load test.