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

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

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