Rate Limits

Current contract

Source reviewed 2026-09-10 (9a6a273); deployed configuration not verified.

There are three distinct controls:

• Endpoint throttling: opt-in SlowAPI decorators, keyed by client IP.
• Workspace/key quotas and concurrency: separate services, applied on specific execution paths. A quota is not proof that every route has an IP throttle.
• Upstream limits: the connected provider can independently reject a request.

The application constructs Limiter(key_func=get_remote_address) without explicit Redis storage or response-header enablement. The reviewed local instance uses MemoryStorage and has headers disabled. Configuring the application’s Redis cache does not automatically configure SlowAPI storage. Do not assume shared cross-worker throttling until the operator verifies it.

Headers and error body

X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After are not guaranteed by the current endpoint limiter configuration. Use them when present; do not require them for parsing a response.

The current default SlowAPI rejection is HTTP 429 with a string-valued error:

{"error":"Rate limit exceeded: 10 per 1 minute"}

This differs from the structured provider error PROVIDER_RATE_LIMITED and from quota error envelopes. Clients must inspect the HTTP status and the type of error, not assume error.code always exists. The request-ID middleware normally supplies X-Request-Id; intermediary-generated failures may not.

Explicitly decorated public mutations

The values below are configuration policy names, not deployment guarantees.

Operation	Policy
POST /v1/chat/completions	rate_limit
POST /v1/conversations/{conversation_id}/attachments	rate_limit
PATCH, DELETE /v1/conversations/{conversation_id}	rate_limit
Conversation sync/archive/restore/share/transfer	rate_limit
Participant update/removal	rate_limit
POST /v1/assets/{asset_id}/retry	rate_limit
Project create/update/delete and project-file removal	rate_limit
Project-file upload	upload_rate_limit
POST /v1/audio/transcriptions	rate_limit
Audio generation, retry and synchronous speech	tts_rate_limit

Known gaps

The source audit found no explicit SlowAPI registration on:

• POST /v1/conversations
• POST /v1/audio/generations/{job_id}/cancel
• POST /v1/actions/{slug}/runs
• POST /v1/actions/{slug}/runs/{run_id}/cancel

These findings do not imply missing authentication or every other protection. They do mean the earlier claim that all mutations are explicitly rate-limited was incorrect. Control Plane and User App coverage is also partial; those are not supported developer integration surfaces.

Retry guidance

• Bound retries and use exponential backoff with jitter for transient read failures and requests known not to have executed.
• Honor a valid Retry-After value when supplied by the responding layer.
• An upstream 429 does not mean that the provider session is permanently dead.
• A timeout after a write may leave the outcome uncertain. Reconcile the existing job/run using its identifier and idempotency contract before retrying.
• Stop automatic retries for invalid credentials, authorization refusal or a non-retryable feature error. Do not reconnect an account solely because it is temporarily rate-limited.

Operator acceptance requirements

Before claiming distributed enforcement, verify the limiter backend, trusted proxy/client-IP handling, restart behavior, worker-to-worker counters, 429 headers/body and a real threshold-crossing test. GHOSTMIND_RATE_LIMIT_ENABLED can disable endpoint throttling; local tests commonly disable it and therefore do not by themselves prove enforcement.

See Errors and API overview for the full public surface.