REST API

Errors

All 4xx and 5xx responses carry a JSON body of the form { "detail": "…" }. The SDK logs each error via your configured logger and never throws to the caller.

Status codes

Status	Meaning	Retry?
`200 OK`	Batch accepted. Some events may be deduplicates — see `duplicates` in the body.	—
`400 Bad Request`	Payload failed Zod validation (size, shape, enum value, ISO timestamp).	No. Fix the client.
`401 Unauthorized`	Missing / malformed Bearer header, unknown key, or revoked key.	No. Rotate the key.
`403 Forbidden`	Key is valid but scope does not permit this endpoint.	No. Issue a key with the correct scope.
`413 Payload Too Large`	Batch exceeds the per-endpoint body limit (5 MB / 10 MB).	No. Reduce the batch.
`429 Too Many Requests`	Rate limit hit on the per-endpoint budget.	Yes, after `Retry-After`.
`500 / 502 / 503 / 504`	Transient server issue.	Yes. SDK retries and opens a circuit breaker after repeated failures.

Error response shape

JSON

{
  "detail": "events[0].timestamp: Invalid date string, expected ISO 8601"
}

SDK behavior

4xx: batch dropped without retry. Most commonly a client bug (bad payload, wrong scope) — check your logger output.
5xx or network failure: counted as a failure. After repeated failures the SDK opens a short-lived circuit breaker and drops new batches during that window.
Partial success: not a concept. Ingest is all-or-nothing per batch; dedup on clientEventId means safe retries never double-count.