Skip to main content
This page describes how the Ingestion API behaves under failure: the error envelope, which status codes to retry, and the request limits. It applies to the /v1/ingest, /v1/ingest/multi, and /v1/traces endpoints; the coding-agent /v1/otel/... routes use different response shapes and are documented on the coding agents page.

​
Response envelope

JSON responses share one envelope:
​
boolean
Whether the request was accepted.
​
number
Number of events accepted. 0 on failure.
​
string
Human-readable explanation. Present on failures and on some successes (for example No events provided on an empty batch).
​
string
UUID identifying the request — your X-Request-ID header value if it was a valid UUID, otherwise server-generated. Include it when contacting support.
​
boolean
Present and true on 503 responses. When set, resend the same request after a backoff.
​
object
On /v1/ingest/multi successes only: accepted-event counts per messageType.
Two exceptions to the JSON envelope: 404 returns the plain-text body Not Found, and protobuf requests to /v1/traces receive OTLP protobuf bodies on success and on 503.

​
Status codes

400 validation errors name the first failing event by index (for example Event 3: invalid 'timestamp' (must be an ISO 8601 date-time when provided)), and nothing from the batch is stored — fix the event and resend the whole request.

​
Retries

  • Retry 503 and 500 responses, and network errors or timeouts, with exponential backoff and jitter.
  • Honor the retryable field when present: retryable: true means resend the same request unchanged.
  • Do not retry 400, 401, 404, or 413 without changing the request — they fail identically every time.
  • Resending an unchanged request to the endpoints on this page does not create duplicate data. Send the same X-Request-ID on retries to correlate attempts in your logs.

​
Limits

Batching guidance:
  • Group events into batches instead of sending one request per event; a single request can carry up to 1,000 events within 5 MB.
  • A batch is validated as a whole: one invalid event rejects the entire request with 400 and nothing is stored.
  • If a batch approaches 5 MB, split it into smaller batches.

​
Environments

Events are tagged with an environment: development, staging, or production (the default).
  • The request-level environment field on /v1/ingest and /v1/ingest/multi must be exactly one of those three values; anything else returns 400.
  • Per-event environment values on /v1/ingest, and moda.environment / deployment.environment attributes on /v1/traces, are normalized case-insensitively: dev and develop map to development, stg and stage to staging, prod to production. Unrecognized values fall back to production.

​
Key revocation

Revoking an ingestion key takes effect within 60 seconds: the server caches successful key validations for up to 60 seconds, so a just-revoked key may be accepted briefly before requests start returning 401. Failed validations are never cached — an invalid key fails immediately.

​
Next steps