Limits and idempotency

Rate limitsCopy Anchor Link

Vene sets two limits for your organization. Ask Vene for your numbers.

• Requests per minute. Every request to /v1, including MCP, counts toward one per-minute window. Over the limit, Vene answers 429 rate_limited with a Retry-After header: the seconds until the next window.
• Running actions. Actions that are queued, in_progress, waiting_for_answer, or waiting_for_callback count as running. At the limit, creating another action answers 429 rate_limited with Retry-After: 60. Reads, answers, and cancels still work.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many actions are running for this client"
  }
}

Request limitsCopy Anchor Link

Each input field has its own limits, such as 1 to 10 pharmacies in a stock check. The action types list them field by field.

IdempotencyCopy Anchor Link

Every create needs an Idempotency-Key, because a create starts real phone calls. When a response is lost to a timeout or a dropped connection, you cannot tell whether Vene got the request. Retry with the same key, and Vene returns the action it already created instead of calling the pharmacy a second time. A new key always creates a new action, since two identical requests can both be meant, such as checking the same prescription today and again tomorrow.

• Use any unique string, such as a UUID, up to 255 characters.
• A retry with the same key and the same body returns the action already created, with 201, as it is now.
• Vene compares bodies by content, so key order does not matter.
• The same key with a different body answers 409 idempotency_conflict.
• Vene remembers a key for 24 hours. After that, the key can create a new action.

POST /v1/actions HTTP/1.1
Host: api.venehealth.com
Authorization: Bearer <api_key>
Idempotency-Key: <idempotency_key>
Content-Type: application/json

Over MCP, pass idempotency_key as an argument to a create tool. It behaves the same way.

Answers and cancels need no key, because a repeat cannot do the work twice. A repeated answer is refused: 409 action_not_waiting once the action has moved on, or 400 invalid_request while other questions are still open. A repeated cancel answers 409 action_ended.