Limits and errors
Limits
| Limit | Value |
|---|---|
| Posts per connected member, per app | 30 a minute |
| Posts per member, across all apps | 60 an hour |
| API requests per access token | 300 a minute |
| Upload size | 2 GB per file |
| Uploads per member | 10 GB a day |
| Apps per developer account | 5 |
| Redirect URIs per app | 5 |
Error format
Every API error has the same JSON shape:
{ "error": { "code": "invalid_arguments", "message": "content, delta_json or files is required" } }Branch on code; message is for people and may change.
| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 401 | invalid_token | Token missing, expired or revoked | Refresh the token; if that fails, reconnect the member |
| 403 | insufficient_scope | The member didn’t grant the scope this call needs | Ask for the scope in a new authorization |
| 403 | app_suspended | Treechat suspended your app | Contact Treechat |
| 404 | not_found | Doesn’t exist, or the member can’t see it | Don’t retry |
| 422 | invalid_arguments | A field is missing, unknown or invalid | Fix the request |
| 409 | idempotency_conflict | The Idempotency-Key was already used for a different request | Use a new key for a new post |
| 409 | quote_expired, quote_consumed | An internal step went stale | Retry with the same key |
| 429 | rate_limit_exceeded, daily_limit_reached | A posting limit was hit | Wait, then retry with the same key |
| 4xx | rejected | Treechat refused the post (for example, no access to that thread) | Read message; don’t retry unchanged |
| 4xx/5xx | request_failed | A read or upload failed | Retry reads; check upload fields |
401 and 403 responses also carry a WWW-Authenticate: Bearer error="…" header, with the needed scope on insufficient_scope.
When the per-token request limit (300 a minute) is hit, the response is 429 with plain text Retry later and a Retry-After header in seconds, not the JSON shape above.
Retries and idempotency
Every POST /posts needs an Idempotency-Key header: 1 to 64 letters, digits, ., _, : or -. Pick one key per post you mean to make, for example episode-42.
- Same key, same body: you get the original result back, never a second post. Retrying after a timeout is safe.
- Same key, different body:
409 idempotency_conflict. - Keys are per app and per member, so two members can use the same key.
Post responses:
| Status | state | Meaning |
|---|---|---|
201 | completed | Posted. thread_id and post_id are final. |
202 | dispatching or uncertain | Treechat hasn’t confirmed it yet. Poll GET /operations/{operation_id} until completed or rejected. Don’t retry with a new key; that could post twice. |
4xx | rejected | Not posted. See error.message. |
GET /operations/{id} returns the same shape with 200 once completed.