Errors & troubleshooting

Every error status the Obsivara ingest API can return, what causes it, and how to fix it.

Error reference

401 — Missing Bearer token

Returned when the Authorization header is absent entirely.

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

Missing Bearer token

Every request to /ingest/* must include:

Authorization: Bearer obs_live_YOUR_KEY

401 — Invalid API key

Returned when the key in the Authorization header is not recognised — it may be malformed, expired, or has been deleted.

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

Invalid API key

Create a fresh key at Settings → API Keys in the Obsivara dashboard. Keys start with obs_live_.

403 — Wrong scope

The key is valid but was created without the ingest:write scope. For example, a read-only key will be rejected by all /ingest/* routes.

HTTP/1.1 403 Forbidden
Content-Type: text/plain

API key lacks the ingest:write scope

Recreate the key and choose the ingest:write scope (or * for full access).

400 — Invalid JSON

Returned when the request body cannot be parsed as JSON.

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Invalid JSON body

Common causes: trailing commas, unquoted keys, binary body. Ensure the Content-Type: application/json header is set and the body is valid UTF-8 JSON.

400 — events must be an array

Returned by /ingest/batch when the events key is missing or not an array.

HTTP/1.1 400 Bad Request
Content-Type: text/plain

events must be an array

The correct batch envelope is:

{ "events": [ { "type": "run_start", "data": { ... } } ] }

400 — All events failed validation

Returned only when every event in the batch fails schema validation (accepted is 0). The body is the normal ingest envelope: errors lists each rejected event by its zero-based index with the validation error message. (If some events are valid, the request instead returns 202 — see “Partial batch success” below.)

HTTP/1.1 400 Bad Request
{
  "accepted": 0,
  "rejected": 1,
  "errors": [
    { "index": 0, "error": "runId must be a valid UUID" }
  ]
}

Check each flagged field against the Event schema reference. The most common causes are:

• runId is not a valid UUID — use run_start first to obtain one, or generate a UUID v4.
• A required numeric field (promptTokens, durationMs, etc.) is missing or is a string.
• status is not one of the accepted enum values.

413 — Batch too large

The batch contains more than 1,000 events.

HTTP/1.1 413 Payload Too Large
Content-Type: text/plain

Max 1000 events per batch

Split the payload into multiple requests. If you need high-throughput ingest, send batches in parallel.

429 — Plan limit exceeded

Your workspace has hit the ingest quota for the current billing period.

HTTP/1.1 429 Too Many Requests
Content-Type: text/plain

Monthly event limit reached for your plan

Upgrade your plan in the dashboard, or contact support if you need a temporary quota lift.

Partial batch success (202 with rejections)

When a batch contains a mix of valid and invalid events, the valid events are accepted and the invalid ones are rejected. The response is still HTTP 202, but rejected will be greater than zero and errors will list the per-index failures:

HTTP/1.1 202 Accepted
{
  "accepted": 4,
  "rejected": 1,
  "errors": [
    {
      "index": 2,
      "error": "runId must be a valid UUID"
    }
  ]
}