Skip to content

Limits and errors

Limits

LimitValue
Posts per connected member, per app30 a minute
Posts per member, across all apps60 an hour
API requests per access token300 a minute
Upload size2 GB per file
Uploads per member10 GB a day
Apps per developer account5
Redirect URIs per app5

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.

HTTPcodeMeaningWhat to do
401invalid_tokenToken missing, expired or revokedRefresh the token; if that fails, reconnect the member
403insufficient_scopeThe member didn’t grant the scope this call needsAsk for the scope in a new authorization
403app_suspendedTreechat suspended your appContact Treechat
404not_foundDoesn’t exist, or the member can’t see itDon’t retry
422invalid_argumentsA field is missing, unknown or invalidFix the request
409idempotency_conflictThe Idempotency-Key was already used for a different requestUse a new key for a new post
409quote_expired, quote_consumedAn internal step went staleRetry with the same key
429rate_limit_exceeded, daily_limit_reachedA posting limit was hitWait, then retry with the same key
4xxrejectedTreechat refused the post (for example, no access to that thread)Read message; don’t retry unchanged
4xx/5xxrequest_failedA read or upload failedRetry 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:

StatusstateMeaning
201completedPosted. thread_id and post_id are final.
202dispatching or uncertainTreechat 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.
4xxrejectedNot posted. See error.message.

GET /operations/{id} returns the same shape with 200 once completed.