Rate limits

Every /api/v1/* response tells you exactly where you stand in your window, so you never have to guess your quota. Read the headers on the response you already have — do not hard-code a number.

Runnable. Every header and status on this page was captured live from the partner sandbox at https://phosra-api-sandbox-production.up.railway.app on 2026-07-06. The /api/v1/platforms read used below needs no API key, so you can reproduce the exact bytes.

The limit

Tier	Default limit	Window	Keyed by
Sandbox / free	100 requests	per 60 s (rolling)	your developer org (authenticated) or source IP (unauthenticated)
Paid	Raised per plan	per 60 s	your developer org

The default of 100 requests/minute is the free-tier org limit (DefaultFreeRateLimitRPM). Authenticated calls are counted per developer org — every key in the org shares one bucket — so adding keys does not add quota. Unauthenticated calls (the sandbox read routes) are counted per source IP.

Discovery reads are unmetered. The unauthenticated OCSS discovery surface — /.well-known/ocss/trust-list, profiles, and Annex B editions — carries no rate-limit headers and is not counted against your window. Only the /api/v1/* surface is metered. Poll discovery cheaply with ETags.

Read your window off every response

Every metered response carries three headers. Read them and you always know your exact standing — no fixed quota to hard-code.

Header	Meaning	Example
`X-RateLimit-Limit`	Ceiling for the current window	`100`
`X-RateLimit-Remaining`	Requests left before a `429`	`99`
`X-RateLimit-Reset`	Unix epoch seconds when the window resets	`1783321140`

bash

curl -s -D - -o /dev/null \
  https://phosra-api-sandbox-production.up.railway.app/api/v1/platforms \
  | grep -i x-ratelimit

text

x-ratelimit-limit: 100
x-ratelimit-remaining: 99
x-ratelimit-reset: 1783321140

X-RateLimit-Reset is Unix epoch seconds, not a duration and not milliseconds. To sleep until reset: wait = max(0, reset - now_seconds).

What a 429 looks like

When you exhaust the window you get 429 Too Many Requests with Retry-After (seconds) and the same three counters, so a single response tells you both how long to wait and that you are fully drained (remaining: 0). Captured live after exhausting the 100-request window:

text

HTTP/2 429
content-type: text/plain; charset=utf-8
retry-after: 60
x-ratelimit-limit: 100
x-ratelimit-remaining: 0
x-ratelimit-reset: 1783321440
 
Too Many Requests

Two 429 bodies, one contract. The per-IP throttle on unauthenticated routes returns the plaintext body above. The per-org limiter on authenticated routes returns the machine-readable house envelope instead — same status, same intent:

json

{ "error": "Too Many Requests", "message": "rate limit exceeded", "code": 429 }

Branch on the status code (429) and honour Retry-After — never on the body shape. See the errors reference.

Handle it: wait for the reset, then retry

Do not retry a 429 immediately — sleep until the window resets, then send the request exactly once. Retry-After (seconds) is the simplest signal; X-RateLimit-Reset (absolute) is equivalent.

bash
BASE=https://phosra-api-sandbox-production.up.railway.app
# Dump headers + status for one request
HDRS=$(curl -s -D - -o /dev/null -w "HTTP_CODE:%{http_code}" \
  -H "Authorization: Bearer $PHOSRA_API_KEY" \
  "$BASE/api/v1/families")
 
if echo "$HDRS" | grep -q "HTTP_CODE:429"; then
  RESET=$(echo "$HDRS" | tr -d '\r' | awk 'tolower($1)=="x-ratelimit-reset:"{print $2}')
  WAIT=$(( RESET - $(date +%s) )); [ "$WAIT" -lt 1 ] && WAIT=1
  sleep "$WAIT"
  # ...then retry the request once
fi

Staying under the limit

Read, don't assume

Watch X-RateLimit-Remaining and slow down as it approaches 0 instead of sprinting into a 429.

Poll discovery with ETags

Trust-list and edition reads are unmetered and support If-None-Match — a 304 costs you nothing. See Versioning.

Batch where the API allows

Prefer bulk-upsert rule writes over one call per rule; prefer a single fan-out enforce over per-child calls.

One bucket per org

Adding keys does not add quota — they share the org window. Need more? Contact us to raise rate_limit_rpm on your plan.