PAYLOAD_TOO_LARGE

What happened

POST /v1/events accepts a JSON body up to 256 KiB. The request you sent was larger, so it was rejected before it reached the queue. This is checked two ways: against the Content-Length header, and against the actual size of the parsed body.

Events are placed whole onto a queue with a 1 MiB hard cap. The 256 KiB limit keeps every event well under that cap.

{
  "error": {
    "type": "invalid_request_error",
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Event payload must be 262144 bytes or smaller",
    "status": 413,
    "doc_url": "https://docs.thewitn.com/docs/errors/payload-too-large"
  }
}

How to fix

Send less data per event. Most oversized bodies come from large blobs inside properties.

• Keep properties to the fields the evaluator and billing need: value, attribution, and settles_at.
• Move large metadata (full documents, transcripts, images) to your own storage and send only a reference, such as a URL or an id.
• Split one large event into several smaller events if each part stands on its own.

Limit

The default limit is 256 KiB. Self-hosted deployments can change it with the EVENT_INGEST_MAX_BODY_BYTES environment variable, but it must stay below the 1 MiB queue cap.