Errors & Rate Limits

Response shape

Every error response has the same shape:


{
  "error": {
    "code": "INVALID_PAYLOAD",
    "message": "channelId is required."
  }
}

Code	Status	Meaning
`AUTH_REQUIRED`	401	No Authorization header or malformed Bearer token
`INVALID_KEY`	401	Token doesn’t match a known key
`REVOKED_KEY`	401	Token was revoked. Create a new one
`RATE_LIMITED`	429	See `Retry-After` header. 300 req/min per key
`SUBSCRIPTION_INACTIVE`	402	Site’s subscription is paused. Events will resume when billing is current
`INVALID_PAYLOAD`	400	Body validation failed. Message has details
`CHANNEL_NOT_FOUND`	404	The supplied `channelId` is not assigned to this site
`CONVERSION_NOT_FOUND`	404	The conversion doesn’t exist or belongs to a different site
`LEAD_NOT_FOUND`	404	No conversion for this `telegramUserId` on this site
`IDEMPOTENT_REPLAY`	200	Returned with header `X-Idempotent-Replay: true`
`API_DISABLED`	503	The public API is paused on the deployment. Contact support
`INTERNAL_ERROR`	500	Unexpected server-side error. Safe to retry

429 — wait Retry-After seconds, then retry.
5xx — exponential backoff (start 1s, double up to 60s). Use Idempotency-Key to avoid duplicates.
401 / 402 / 403 / 404 / 400 — do not retry; fix the request.

All endpoints support CORS preflight (OPTIONS). Origin is * so the API is reachable from any reverse proxy or backend.