Errors and retries

The ingest API answers errors as JSON with a machine-readable code. Decide what to do by the status: retry 408, 429, 5xx and network failures with the byte-identical body, fix everything else. A 202 is final, even when it reports dropped events.

Error bodyCopy Anchor Link

{
  "code": "validation_failed",
  "detail": "The batch does not match the event schema.",
  "errors": [{ "path": "events.0.name", "message": "The events.0.name field must be a name without surrounding whitespace." }]
}

Some answers are produced before a request reaches the API and carry { "message": "…" } instead of a code: a path that does not exist or whose key does not look like a key (404), a body the web server refuses as too large (413), and maintenance (503, with Retry-After). Every answer, errors included, carries the CORS headers, so a browser can read it.

Status codesCopy Anchor Link

Error codesCopy Anchor Link

Error codes may be added within v1. Treat an unknown code by its status.

Retry policyCopy Anchor Link

Retry on 408, 429, any 5xx, network errors and timeouts. Do not retry any other 4xx, and never retry a 202.

• Resend the byte-identical body, with the same batch id. Serialise the batch once and keep the bytes.
• Back off with full jitter: before retry n (0-based), wait a random time between 0 and min(cap, base × 2ⁿ). The Node SDK uses a base of 250 ms and a cap of 4 seconds.
• Honour Retry-After when a 429 or 503 carries it: wait that many seconds instead of the backoff. Bound the wait to what your caller can afford.
• Give up after a few attempts and report the failure. A batch that was never answered with 202 may or may not have been stored; resending it later under the same id is safe.

A browser that flushes on page hide with sendBeacon cannot read the answer. That is accepted: it cannot retry either.

IdempotencyCopy Anchor Link

The batch id is the idempotency key. The server stores a batch id once per project: sending the same batch again within a day is counted and stored once, and answered with the same receipt. The server keys on the id, not the bytes, so a different body under a used id is not stored. Always give a new batch a new id, and a retry the old one.

A client that accepts its own idempotency key from the caller (an order number, a webhook event id) derives the batch id from it, so every SDK agrees on the id:

batch = UUIDv8( SHA-256( "mirafive:batch:" ‖ key ) )

1. Encode "mirafive:batch:" followed by the key as UTF-8. The key must not be empty.
2. Hash with SHA-256 and take the first 16 bytes.
3. Set the version: bytes[6] = bytes[6] & 0x0f | 0x80.
4. Set the variant: bytes[8] = bytes[8] & 0x3f | 0x80.
5. Format as a lower-case UUID, 8-4-4-4-12 hex digits.

Worked example for the key order-981:

import hashlib
import uuid


def batch_id(key: str) -> str:
    if key == "":
        raise ValueError("the idempotency key must not be empty")
    b = bytearray(hashlib.sha256(("mirafive:batch:" + key).encode("utf-8")).digest()[:16])
    b[6] = b[6] & 0x0F | 0x80
    b[8] = b[8] & 0x3F | 0x80
    return str(uuid.UUID(bytes=bytes(b)))


print(batch_id("order-981"))  # 274e05f0-4dd7-8db9-a563-87ea5c891487

More test vectors from the protocol fixtures (batch-id.cases.json):

Keys are used exactly as given: case, whitespace and Unicode normalisation all change the id.

Rate limitsCopy Anchor Link

Limits count per client address (an IPv4 address or an IPv6 /64) and per key. Website keys are public, so their budgets count per key and client network: a copied key only drains its own bucket. The current limits:

Batches are charged per event; a batch the server cannot read costs one. A limit refuses only once its bucket is spent, so a batch larger than the remaining budget still passes once. Over a limit, the answer is 429 rate_limited with Retry-After in seconds. Limits can change: rely on 429 and Retry-After, not on these numbers.

Exposed secret keysCopy Anchor Link

A secret key is exposed once it has been seen from a browser: any request carrying an Origin or Sec-Fetch-Site header, which browsers add and server runtimes and curl do not. That also happens when the key is sent in a URL path from a browser.

Then find where the key reached a browser: a public env var prefix (NEXT_PUBLIC_, VITE_, PUBLIC_, NUXT_PUBLIC_), a client bundle, or a server call made from a page.