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 SDK surfaces this through the same discriminated union every other method uses — pattern-match on result.ok === false and check result.error.code === 'RATE_LIMIT_EXCEEDED'.

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.

@phimajor-solutions/pwfabric-sdk will ship a withRetry() helper that does this in a future release; until then, wrap calls in your own retry loop.

AI credits

AI credits track AI cost separately from REST volume — internally this economy is metered in a unit called Φ. Each plan ships with a monthly allotment of credits; the per-plan amounts are on the pricing page.

When you hit the cap

PhiCo turns are refused until you top up from World settings → Billing.
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

A typed SDK helper (client.usage.current()) is planned for a future release — until it ships, call the endpoints above with your bearer token.