docs/api-reference/payload-limits.mdx - next - githubmirror/novu

docs/api-reference/payload-limits.mdx
89 строк3 KB
Dima Grossman
docs(docs): adopt Mintlify components across key pages fixes DOC-367 (#11663)
26 июн 2026, 09:00
26 июн 2026, 09:00e241cbf
---
title: 'Payload Limits'
description: "Understand payload size limits for Novu API requests and workflow triggers. Structure event payloads to avoid validation failures and rejected requests."
---

Payload size limits are an essential functionality for ensuring optimal performance and reliability of the system. They safeguard system resources by preventing oversized payloads from impacting API performance and ensure efficient processing of event triggers.

## Payload size limit

All event trigger operations have a **512KB (524,288 bytes)** payload size limit. This limit applies to the following endpoints:

- **Trigger event** - Single event triggers
- **Bulk trigger event** - Batch event triggers
- **Broadcast event** - Events sent to all subscribers

<Note>
  Attachments are excluded from the payload size calculation and have a separate size limit.
</Note>

## What counts towards the limit

The payload size limit includes:
- Event payload data
- Custom data and properties
- All other request body content

## Error messages

When your payload exceeds the 512KB limit, you'll receive an error response indicating the exact size and the limit exceeded.

<Tabs>
  <Tab title="Single event trigger">

For single event triggers (`/events/trigger`), the error response will be:

```json
{
  "statusCode": 413,
  "message": "Payload size (524342 bytes) exceeds maximum allowed size of 524288 bytes (512KB). Note: Attachments are excluded from this limit."
}
```

  </Tab>
  <Tab title="Bulk trigger event">

For bulk event triggers (`/events/trigger/bulk`), the error response includes the index of the event that exceeded the limit:

```json
{
  "statusCode": 413,
  "message": "Event at index 1 (workflow: \"workflow-name\") has payload size (524342 bytes) exceeds maximum allowed size of 524288 bytes (512KB). Note: Attachments are excluded from this limit."
}
```

<Note>
  When using bulk trigger, each event in the array is validated individually against the 512KB limit. Ensure that every event payload stays within the limit.
</Note>

  </Tab>
  <Tab title="Broadcast event">

For broadcast events (`/events/trigger/broadcast`), the error response will be:

```json
{
  "statusCode": 413,
  "message": "Payload size (524342 bytes) exceeds maximum allowed size of 524288 bytes (512KB). Note: Attachments are excluded from this limit."
}
```

  </Tab>
</Tabs>

## Attachment size limit

Email attachments have a separate size limit:
- **Total attachment size**: 20MB for all attachments included in an email.
Attachments do not count towards the 512KB payload limit

<Tip>
  For more information about sending email attachments, refer to the [Sending Attachments](/platform/integrations/email#sending-attachments) documentation.
</Tip>

## Related documentation

- [Rate Limiting](/api-reference/rate-limiting) - Learn about API rate limits
- [Trigger Event](/api-reference/events/trigger-event) - Single event trigger API
- [Bulk Trigger Event](/api-reference/events/bulk-trigger-event) - Batch event trigger API
- [Broadcast Event](/api-reference/events/broadcast-event-to-all) - Broadcast to all subscribers