Rate limits and errors

Rate limits

Limits are counted across all Ketvia API servers, not per server.

Surface	Limit	Counted per
Web API reads	100 requests per minute	installation
Web API writes	50 requests per minute	installation
POST /messages	additionally 1 message per second, burst 5	conversation
Files (upload and download)	20 requests per minute	installation
Incoming webhooks	1 request per second sustained, burst 5	webhook
responseUrl posts	5 uses and 30 minutes per token; 50 per minute	installation
Block interactions	30 per minute	member and Kit
Slash commands	10 per minute	member and command
Event deliveries (to you)	10 in flight per installation, 50 per Kit	installation

The Web API reference lists the family (read, write or files) of each method. Over the limit, Ketvia answers 429 rate_limited with a Retry-After header in seconds. Wait at least that long before retrying, and spread bursts out instead of retrying in a tight loop. The SDK does this for you (2 retries by default).

Error format

Every error is JSON:

{
  "code": "missing_scope",
  "message": "This token lacks the messages:write scope.",
  "correlationId": "01J9Z6Q4X8T3V5N7K2M4P6R8S0"
}

code is stable and meant for your code; message is for people and can change. Quote the correlationId when you contact support. Validation errors name the field path but never echo the submitted values.

Error codes

Status	code	Meaning and what to do
400	validation_error	The request is malformed. Fix the field named in message.
401	invalid_token	The token is missing, malformed, expired or revoked, or the Kit was uninstalled. Comes with a WWW-Authenticate header. Do not retry with the same token.
403	missing_scope	The token lacks the scope this method needs. The header X-Ketvia-Required-Scope names it. Add the scope to the manifest, upload a new version, and issue a new token.
403	forbidden	The token type cannot do this: for example a bot token adding a reaction or uploading a file in v1 (use a user token), or a user-only method.
404	not_found	The object does not exist or this token may not see it. Ketvia never answers 403 for existence. For bot tokens, check that the Kit bot was added to the channel.
409	idempotency_conflict	The same Idempotency-Key was used with different content.
409	conflict	Another conflict, for example rotating a bot token that was already rotated.
410	gone	An incoming webhook was disabled: its channel was archived or the Kit bot was removed.
413	payload_too_large	The body is too large (64 KB for webhooks; file size limits for uploads).
502	kit_unavailable	(Member routes only.) Your Kit did not answer an interaction or slash command within 3 seconds, or answered with an error.
429	rate_limited	Too many requests. Retry after Retry-After seconds.
500	internal_error	Something failed on Ketvia’s side. Retry reads later; retry writes only with an Idempotency-Key.

Pagination

List methods take cursor and limit query parameters and return nextCursor:

curl -s 'https://api.ketvia.com/api/v1/conversations?limit=100' \
  -H "Authorization: Bearer $KETVIA_TOKEN"

• limit is 1 to 200 and defaults to 50.
• nextCursor is an opaque string; pass it unchanged as cursor for the next page. It is null on the last page.
• Message lists are newest first.

Idempotency

POST /messages accepts an Idempotency-Key header (1 to 255 printable ASCII characters). For 24 hours:

• the same key with the same content returns the stored message with 200 instead of posting again (the first call answers 201);
• the same key with different content answers 409 idempotency_conflict.

Use one key per logical message, for example derived from your own event id, and reuse it on every retry.