Errors and limits
What a refused call answers, and the limits the API enforces.
Errors
A refused call answers with a JSON body { statusCode, error, message }. The message says what is wrong.
| Status | Message | Meaning |
|---|---|---|
| 400 | varies | A required field is missing, no target was given, or a state value is not allowed (layout, countdownStyle, progressStyle, versus.activeSide, countdownTo, segments). The message names the field. |
| 401 | API_KEY_REQUIRED / INVALID_API_KEY | The x-api-key header is missing or wrong. |
| 402 | PLAN_SELECTION_REQUIRED | The team has not chosen a plan. Choose one in the dashboard (Free works). |
| 402 | FREE_TIER_LIMIT_REACHED | The Free plan's monthly pushes are used up. See delivery and billing. |
| 403 | ACCOUNT_SUSPENDED | The account that owns this team is suspended. See the Terms of Service. |
| 404 | No activity matched | None of the activity ids sent were found in this container. |
| 413 | The "state" object is too large | The state is over 16KB. |
| 413 | The notification is too long | A push notification is over 4KB. |
| 429 | varies | Too many requests in a short time. Wait, then try again. |
| 500 | Internal Server Error | Something failed on our side. Try again later. |
Limits
| What | Limit |
|---|---|
state | 16KB of JSON. |
segments | 12 steps. Labels are cut at 60 characters. |
countdownTo | Unix epoch seconds, as a number. |
| Text on the card | See text that fits. |
| Images | Full https URLs the phone can download. WebP is best; PNG and JPEG also work; SVG does not. See images that fit. |
| Push notification | 4KB. |
| Requests | No fixed rate limit. Very heavy traffic can be blocked with a 429. If one activity gets several updates within 45 seconds, only the newest is sent. |
| Phones per group or reuse button | No limit. |
| Webhook answer | 8 seconds. |
