> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pushctl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and rate limits

> Handle Pushctl HTTP errors, validation responses, and per-application rate limits.

## HTTP status codes

| Status | Meaning                                                        | Action                                          |
| ------ | -------------------------------------------------------------- | ----------------------------------------------- |
| `200`  | Successful read, update, or repeated event                     | Process the response                            |
| `201`  | New delivery event created                                     | Process the response                            |
| `202`  | Notification accepted for asynchronous fanout                  | Store the notification ID and poll if needed    |
| `401`  | Missing, invalid, or revoked token                             | Check the bearer header and rotate if necessary |
| `403`  | Token lacks the required ability                               | Use a correctly scoped token                    |
| `404`  | Resource does not belong to this application or does not exist | Check the opaque ID and application             |
| `422`  | Validation failed                                              | Read the `message` and `errors` object          |
| `429`  | Rate limit exceeded                                            | Back off and retry after the indicated interval |

## Rate limits

Limits are per authenticated application and reset each minute.

| Bucket                | Limit        |
| --------------------- | ------------ |
| Notification sends    | 120/minute   |
| Installation writes   | 600/minute   |
| Delivery event writes | 1,200/minute |
| API reads             | 600/minute   |

<Tip>Use exponential backoff with jitter for `429` and transient `5xx` responses. Do not automatically retry permanent `4xx` validation or permission failures.</Tip>

## Important request limits

* 1–500 distinct external user IDs per notification
* 255 characters per user ID and notification title
* 4,096 characters for notification body and provider identifier
* TTL from 0 through 2,419,200 seconds
* 64 characters for collapse ID
* `per_page` from 1 through 100