Concepts

Rate limits & plans

Monthly order quotas, per-minute request limits, and how to handle QUOTA_EXCEEDED and RATE_LIMITED.

Every account is on a plan. The plan sets how many orders you can create per month, how many requests you can make per minute, and whether you can create live keys.

PlanOrders / monthRequests / minuteLive keys
Free free5060No
Basic basic1 000300Yes
Pro pro20 0001 200Yes

New accounts start on Free. Contact 1fly to change plans. Check your plan and current usage with GET /v1/account (any API key, no scope needed), the dashboard, or the MCP tool get_usage:

JSON
{
  "plan": { "id": "free", "name": "Free", "ordersPerMonth": 50, "requestsPerMinute": 60, "liveKeys": false },
  "usage": { "periodStart": "2026-11-01T00:00:00.000Z", "ordersThisPeriod": 12, "requestsThisPeriod": 840, "mcpCallsThisPeriod": 95, "errorsLast24h": 3, "requestsLast24h": 210 }
}

Request rate limit#

Requests are counted in fixed one-minute windows, per API key (per account for dashboard sessions). Every authenticated request counts, reads included. Request number requestsPerMinute + 1 in a window gets:

HTTP
HTTP/1.1 429 Too Many Requests
Retry-After: 17
Content-Type: application/json

{ "error": { "code": "RATE_LIMITED", "message": "More than 60 requests per minute on the free plan. Retry in 17 s.", "requestId": "…" } }

How to handle it:

  1. Wait the number of seconds in Retry-After (the time until the current window ends), then retry the same request. A retried POST /v1/orders must use the same idempotencyKey.
  2. If you hit the limit often, slow down instead: poll an order every 2–3 seconds, not in a tight loop, and page through lists rather than re-reading them.
  3. Spread separate workloads over separate keys. Each key has its own window.

Monthly order quota#

Each POST /v1/orders that creates a new order counts towards ordersPerMonth. Repeats with an existing idempotency key, reads and failed validations do not. The period is the calendar month. Once the quota is used up, creating an order returns:

JSON
{ "error": { "code": "QUOTA_EXCEEDED", "message": "The Free plan allows 50 orders per month; 50 used. Upgrade the plan or wait until the 1st.", "requestId": "…" } }

with HTTP 429. Do not retry QUOTA_EXCEEDED automatically: it will not succeed until the next month or a plan change. Tell the person who runs the integration, and keep serving reads; everything except order creation keeps working.

Note

Both errors use HTTP 429, so always branch on error.code, not on the status alone.

Live keys#

Only Basic and Pro accounts can create 1fly_live_ keys. Live order creation itself is not available yet on any plan (403 LIVE_MODE_UNAVAILABLE).

API version v0.0.1 · Spec generated from source on 2026-11-22Changelog · Prices in so‘m (UZS)