Rate limits and quotas

This page documents the operational limits an API client should design around. Some values are environment-configurable, so client code should read response errors and headers instead of hard-coding every number.

Request rate limiting

The default API rate limit is:

120 requests per 60 seconds

The backend reads these environment variables:

When rate limited, clients receive:

429 Too Many Requests

Clients should back off using the retry hint returned by the deployment when available. If no header is present, use exponential backoff with jitter.

Pagination limits

Entity browsing uses bounded pagination:

GET /api/v1/demo-jobs/{job_ref}/entities/{entity}?limit=100&offset=0

Current maximum page size:

1000 records

Clients should page until:

offset + data.length >= count

Do not assume that a single page can contain a full ledger.

Partner bundle limit

The normalized bundle endpoint is capped so one response cannot accidentally ship an entire large tenant through a JSON response.

Default:

PARTNER_BUNDLE_MAX_RECORDS=25000

Endpoint:

GET /api/v1/demo-jobs/{job_ref}/bundle

If the selected entities exceed the cap:

413 Payload Too Large

{
  "detail": "Bundle too large for one response. Requested 30001 records across 15 entities, which exceeds the partner bundle cap of 25000. Use the entity or export endpoints instead."
}

The cap can be changed by deployment configuration. Treat 413 as a signal to page or export, not as a numeric limit to hard-code into a client.

Recovery options:

• request fewer entities with repeated entity query params
• use paginated entity reads
• use per-entity exports
• use the runtime CSV export pack route when the use case is "download all data"

Dataset storage limits

The current project dataset blob model has write-time guardrails.

Defaults:

If a write would exceed the dataset budget, the API returns a structured error:

{
  "detail": {
    "code": "project_dataset_limit_exceeded",
    "project_id": "proj_123",
    "context": "simulation_step",
    "record_count": 315000,
    "max_records": 300000,
    "estimated_bytes": 140000000,
    "max_bytes": 134217728,
    "message": "Project dataset exceeds current blob storage safety budget"
  }
}

Client action:

• reduce generated scale
• clone into smaller scenario-specific jobs
• avoid long unbounded simulation runs
• export and archive data before destructive reset if needed

Generation admission limits

Fictix estimates generation load before doing expensive work.

Default generation budget:

MAX_WEIGHTED_GENERATION_LOAD=300000

Weighted load is roughly:

estimated_records * quality_multiplier * connector_multiplier

Quality multipliers:

Connector multiplier:

1 + max(0, connector_count - 1) * 0.25

Full system materialization uses at least 6 connector-equivalent units.

If a request is too large:

422 Unprocessable Entity

{
  "detail": "Requested generation load exceeds the server budget (420,000 weighted units for about 145,000 estimated records, quality 'realistic', 8 connectors; budget 300,000). Reduce employees, months_of_history, customers_per_employee, or connector breadth. With the current shape, try <= 85 employees or <= 12 months_of_history."
}

Client action:

• lower generation.employees
• lower generation.months_of_history
• reduce customers_per_employee
• select fewer services
• use clean for broad smoke tests
• create multiple smaller demo jobs instead of one huge tenant

Webhook limits

Webhook subscription limits:

Webhook delivery is billed/metered as webhook_deliveries when quota is configured for the project.

Plan quotas

Plan-level quotas are enforced from the billing catalog. The signed-in Fictix Console is the customer-facing source of truth for an organization's active plan and current usage; do not infer entitlement from a key name or a documentation table alone.

Current default catalog limits:

When quota is exhausted, clients should stop the workflow or surface an upgrade path. Do not auto-retry quota failures. Use the Console to review usage and upgrade eligibility.

Client backoff policy

Recommended general policy:

For POST /api/v1/demo-jobs, retry only with the same request body and same Idempotency-Key.