Errors

Errors return a JSON body with a stable code and a human-readable message. Branch on code, not on the message, which may change.

{ "error": { "code": "alert_too_long", "message": "…", "field": "alert.title", "limit": 100, "actual": 128 } }

Whether to retry

Status	Retry?
400, 413, 422	No. Fix the request first; sending it again gives the same error.
401, 404	No. The URL or token is wrong or no longer valid.
429, 503	Yes, after the number of seconds in the Retry-After header.
Other 5xx	Yes, with backoff. Send an idempotency_key so a retry never creates a second alert.

All codes

Status	Code	Endpoint	Meaning and fix
400	invalid_json	Send	The body is not valid JSON or not valid UTF-8.
401	invalid_send_url	Send	The send URL is wrong, regenerated, revoked, suspended, or its channel was deleted. Copy the current URL from the app.
401	unauthorized	Receipts	The Authorization header does not hold a send URL token.
404	not_found	Receipts	No receipt with this ID was sent by this send URL.
404	invalid_heartbeat_url	Heartbeat	The heartbeat URL is wrong, was regenerated or deleted, or its channel was deleted.
413	request_too_large	Send	The body is larger than 64 KB.
422	invalid_target	Send	alert.title is missing, or a field has an invalid value or forbidden characters. field names the field.
422	alert_too_long	Send	A field is over its limit. The error includes field, limit, and actual.
422	invalid_alert_level	Send	level is not urgent, high, normal, or silent.
422	invalid_emergency	Send	emergency.retry_seconds is under 30, or expire_seconds is under retry_seconds or over 10800.
422	invalid_callback	Send	callback was requested on an alert that cannot be acknowledged.
422	callback_not_configured	Send	callback was requested, but the channel has no enabled callback.
422	encryption_required	Send	The channel accepts only encrypted alerts.
422	invalid_encrypted_message	Send	The encrypted envelope is incomplete or malformed.
429	limit_exceeded	Send	The send URL’s rate limit was reached.
429	rate_limited	All	Too many requests from your network address.
500	create_failed	Send	The alert could not be stored. Retry with the same idempotency_key.
503	server_busy	All	The server is handling too many requests at once. Retry shortly.