Errors

Every response carries a meaningful HTTP status code. A 2xx means the batch was accepted for processing; anything else signals a problem your client should handle explicitly. Error bodies, when present, are JSON.

Success shape

Batched writes (POST /stream/contacts, POST /stream/events) return 202 Accepted with a per-item outcome so partial failures do not block the rest of the batch:

{
  "entity": {
    "successful": 2,
    "failed": 1,
    "items": [
      { "status": "success", "_user_id": "USER-1" },
      { "status": "success", "_user_id": "USER-2" },
      { "status": "error",   "_user_id": "USER-3", "errors": { "_email": ["Invalid format"] } }
    ]
  }
}

Inspect items[] before assuming the whole batch landed. Failed items are safe to retry once fixed.

Status codes

202 Accepted

The batch is accepted for processing. Check the body's items[] for per-record outcomes — some may still have validation errors.

400 Bad Request

The request body is malformed or has the wrong shape (not an array, wrong types, exceeds 100 items). Not retryable — fix the payload first.

{ "message": "Body should be an array" }

401 Unauthorized

The token is missing, revoked or malformed. Not retryable with the same token — check the Authentication guide.

404 Not Found

The project or datasource in the URL does not exist, or the token is not authorized to write to it.

422 Unprocessable Entity

Every item in the batch failed validation. The body lists per-item errors with the same shape as a partial-success 202. Not retryable as-is — fix the items and resubmit.

429 Too Many Requests

You hit the rate-limit window. Retry after X-RateLimit-Reset. See Rate limits.

500 Internal Server Error

Something broke on our side. Retry with exponential backoff; if the failure persists, contact support with the request id.

Retry policy

What's next

• Rate limits — how the X-RateLimit-* headers work.
• API Reference — per-endpoint responses and schemas.