Limits

Two kinds of limits: request rates and field sizes. Both return machine-readable errors.

Rate limits

The API enforces 10,000 requests per minute per account across all /api/v2 endpoints, shared by all API keys and dashboard sessions on the account. Authenticated responses include tracking headers:

Every figure on this page is the allowance you can rely on, not an exact ceiling: you will never be throttled below it, and in some deployments we allow more. Design against the published number and use the response headers below for the live figure.

Past the limit, requests return 429 with a Retry-After header (seconds to wait):

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Retry after 3 seconds.",
    "code": 429,
    "request_id": "req_abc123",
    "doc_url": "https://m8tes.ai/docs/limits#rate-limits"
  }
}

The SDKs retry 429 and 5xx responses with exponential backoff for idempotent methods (GET, PUT, DELETE), and for the run-creating POSTs, which carry an idempotency key so a retry can never start a second run. Any other POST or PATCH is not retried, to prevent duplicate side effects. A RateLimitError only reaches your code once all retries are exhausted.

Idempotency

A run costs money. A timed-out request must not leave you guessing whether you were charged. Send an Idempotency-Key header on any run-creating POST. A retry returns the run the first attempt made, instead of starting a second one:

curl https://api.m8tes.ai/api/v2/runs \
  -H "Authorization: Bearer m8_..." \
  -H "Idempotency-Key: order-4242-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"message": "Close open tickets", "stream": false}'

Supported on POST /runs, POST /runs/first-session, POST /runs/with-files, POST /runs/{id}/reply, POST /runs/{id}/reply/with-files, and POST /tasks/{id}/runs.

• Same key, same request → 200 with the original run's current state and an Idempotent-Replay: true header. Safe to repeat as often as you like.
• Same key, different request → 409 with error.details.error_code = "idempotency_key_reuse". A key is never silently replayed against a call you did not make.
• Keys last 24 hours and are scoped to your account, so two accounts can use the same key string without interfering.
• Failed requests do not bind the key. A 402, 429, or 500 leaves the key free. Fix the cause and retry with the same one.

The SDKs generate a key for every runs.create, runs.start_first_session, runs.reply, and tasks.run automatically, which is what makes their retries safe. Pass your own when a retry must survive a process restart:

run = client.runs.create(
    message="Close open tickets",
    stream=False,
    idempotency_key=f"nightly-sweep-{job_id}",
)

A replayed streaming call is answered as JSON rather than SSE (the run already exists; there is no fresh stream). The SDKs join the existing run's stream. If that run has already finished, they raise with the run id (idempotent_replay_terminal); fetch its result with runs.get(id).

client.settings.update(per_end_user_rate_per_minute=10)

{
  "detail": "Too many requests. Retry after 30 seconds."
}

Field limits

Request fields have size and count caps:

Webhook payloads and inbound events are capped at 256 KB; larger requests return 413.

The metadata field accepts any JSON object under 10 KB serialized. Use it for IDs, labels, and lightweight state, not for large blobs or document content. When a field exceeds its limit, the API returns 422:

{
  "error": {
    "type": "validation_error",
    "message": "metadata must not exceed 10240 bytes serialized",
    "code": 422
  }
}

Next: Errors · Going Live