Errors & rate limits

Comms returns JSON errors and standard HTTP statuses. Unknown failures stay opaque so engine internals never leak to API clients.

Error shape

{ "error": "unauthorized" }

Some rate-limit responses include:

{ "error": "rate_limited", "retry_after": 60 }

Status	Meaning	What to do
200	OK — including idempotent duplicate sends	Treat as success
201	Created (e.g. webhook)	Persist returned id
202	Accepted for delivery	Persist `message.id`
400	Bad request / validation	Fix the payload
401	Missing or invalid key	Check `Authorization` header
403	Valid key, missing scope	Mint a key with the right scope
402	Plan quota reached (messages)	Upgrade, or wait for the period to reset
429	Rate limited	Back off `retry_after` seconds (or 60s default)
5xx	Server error	Retry with backoff + same idempotency key on sends

Defaults (configurable per environment):

Bucket	Default	Applies to
Global Comms API	~100 req / min / caller	All authenticated Comms routes
Send	~60 req / min / caller	`POST /messages` only

Caller identity is derived from the API key (or staff session). Limits are per org + caller.

{ "error": "missing comms_send scope" }

Create a new key (or rotate) with the required scopes from Messages API keys.

Operation	Retry?	Notes
`POST /messages`	Yes, with same idempotency key	Safe
`GET *`	Yes	Read-only
`POST /webhooks`	Careful	May create duplicates if not checked
`POST /contacts`	Careful	Upsert semantics — usually safe