Rate limits & quotas

The PhiWebs API protects every World with two separate ceilings:

REST rate limits — count requests per rolling window, by endpoint class (public, read, write, admin). Limits are platform-tuned and may be adjusted operationally without a version bump.
AI credits — count the credits spent on PhiCo turns, by the work each turn produces; reset each billing period.

Both ceilings degrade gracefully — the API answers with a typed error shape, never a silent drop or a 500.

Rate limit headers

Rate-limited responses carry the current window state:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1718200800

429 response shape

When you exhaust a window, the API returns HTTP 429 Too Many Requests with a Retry-After header in seconds and a typed JSON body:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json
 
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests, please try again later",
    "retryAfter": 42,
    "traceId": "…",
    "timestamp": "2026-06-12T09:30:00.000Z"
  }
}

The envelope is the same for every error, but three different refusals can stop the same request, and a client that only checks for one mishandles the other two:

Code	Status	What it means
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Read `retryAfter` and retry.
`PLAN_LIMIT_EXCEEDED`	403 or 429	A plan ceiling was reached. The error carries `dimension`, `used`, `limit`, `unit` and `planCode`. A standing limit (live apps, records, storage, members) answers 403 and keeps failing until the plan changes; a rolling Φ pace window answers 429 with `Retry-After`, and the same request works again once the window moves.
`CREDIT_LIMIT_EXCEEDED`	402	The Φ wallet is empty. No backoff helps — this needs Φ, not patience.

So branch on the code, not on the status: 402 is not a 429, and a plan ceiling is not congestion.

Recommended backoff

Honour Retry-After. If you must implement your own backoff:

Start with the Retry-After value (or 1 second if missing).
Double on every subsequent 429, capped at 60 seconds.
Add ±25% jitter to avoid thundering-herd reconnects.

Wrap your calls in a retry loop that does this — the API will not retry for you.

AI credits

AI work is metered separately from REST volume, in a unit called Φ. Each plan renews a daily and a weekly AI usage; the Wallet page of your account shows your current usage and your credit balance. AI credits, bought in packs, are used only when the usage runs out and you have turned on “continue with credits”. See Billing & plans.

When you hit the cap

PhiCo turns are refused until the daily or weekly usage renews, or until you continue with credits.
AI credits are charged per turn, based on the work the turn produces — accepting or rejecting the resulting Receipt costs nothing on its own.

Inspecting your usage

Hit the REST endpoints directly:

GET /api/ai/usage           # AI credit ledger spend per period
GET /api/ai/credits/balance # remaining AI credits
GET /api/billing/overview   # plan, period, billing state

Call these with your bearer token; the response carries the same counters your account page shows.