Errors and rate limits

Shape

Every public API error uses the same JSON envelope:

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_cursor",
    "message": "The cursor parameter is not a cursor this API issued.",
    "request_id": "req_7f24a2f8c6b64e699901563a458b5031"
  }
}

The same request ID is returned in X-Request-Id. Log it and include it in a support request. Branch on error.code, not on the human-readable message.

Codes worth handling explicitly

Code	Meaning	What to do
HTTP	Code	Meaning
—	—	—
400	invalid_parameter	A path or query parameter is invalid
400	invalid_cursor	The cursor was altered, truncated, or issued by an incompatible paginator
401	invalid_credentials	The key is missing or unusable
402	subscription_inactive	The account has no active subscription
403	insufficient_scope	The key lacks the endpoint’s scope
403	plan_upgrade_required	The account’s plan does not include the REST API
403	account_closed	The account is scheduled for deletion
404	resource_not_found	The resource is absent from this account
429	rate_limit_exceeded	The credential exceeded its request rate
500	internal_error	Talki hit an unexpected failure

A resource belonging to another account is deliberately returned as the same 404 as a nonexistent resource.

Rate limits

Limits are applied per credential:

Operation	Limit
GET /v1/account	60 requests/minute
Public read endpoints	600 requests/minute

On 429, honour Retry-After when present and add exponential backoff with jitter. Never retry 400, 401, 402, 403, or 404 unchanged.

Write idempotency and conflict codes will be documented when write endpoints are released; no public REST writes are available today.