Limits & quotas

This page covers the resource ceilings — how big a page you can pull, how large a request body may be, how long an identifier can be. These are separate from rate limiting: a rate limit throttles how often you may call (429 Too Many Requests), while a resource limit bounds how much a single call may carry or return (a 400, a 413, or a silently clamped page).

Rate limit vs. resource limit

Pagination page sizes

List endpoints never error on limit, but they don't all behave the same way — some enforce a hard ceiling, some accept anything. Read the column below before you assume a big page works. See Pagination for how to walk every page.

Request-body size caps

There is no single global body cap — the census enforces size in two layers, and a request must clear both:

1. The outer signed-envelope cap — 10 MiB. Every RFC-9421-signed census write is buffered whole by the signature verifier (Verifier.Require) so the content digest can be checked over the exact bytes the handler will read. That buffer is bounded at 10 MiB — the effective default cap on every signed endpoint, including the two every partner calls: POST /api/v1/policies/{policyId}/rules (rule-write) and POST /api/v1/webhooks/inbound/{source} (ingest). Exceed it and verification fails before the handler runs, with a malformed-class OCSS error (not a 413).
2. The inner per-handler cap. Each handler then re-bounds its own body to a tighter, payload-sized limit. How the limit is enforced determines the failure signal:
   • http.MaxBytesReader endpoints fail hard at the boundary — a clean 413 (or, where the read is wrapped in a JSON decoder, a 400).
   • io.LimitReader endpoints silently truncate at the limit, so the validator rejects the now-broken JSON with a 400/malformed — you never see a 413. Don't design against a 413 from these; watch the cap yourself.

Every value below is the exact http.MaxBytesReader / io.LimitReader constant in the census source, paired with the exact method + path it guards.

Outer envelope — all signed census writes

Inner per-handler caps

A real 413, end to end

Post more than a MaxBytesReader cap and you get a 413 with a machine-readable body. This is captured live from the partner sandbox — a 40 KiB body against the 32 KiB accreditation/apply cap:

BASE=https://phosra-api-sandbox-production.up.railway.app
 
# Build a ~40 KiB JSON body — over the 32 KiB accreditation-apply cap
BIG=$(printf 'a%.0s' {1..40000})
printf '{"provider_did":"did:ocss:x","evidence":"%s"}' "$BIG" \
  | curl -s -X POST "$BASE/api/v1/accreditation/apply" \
      -H 'Content-Type: application/json' \
      --data-binary @- -w '\nHTTP %{http_code}\n'

{
  "error": "Request Entity Too Large",
  "message": "request body exceeds the accreditation-apply size bound",
  "code": 413
}

Identifier & field lengths

The name/email bounds are the database column width (VARCHAR(255)) — an over-length value is rejected at write time by Postgres, so it surfaces as a write failure rather than a pre-validated 400. The did:ocss slug bound, by contrast, is live-enforced in the handler — a 200-byte slug is rejected before any lookup. Reproduce it:

BASE=https://phosra-api-sandbox-production.up.railway.app
LONG=$(printf 'a%.0s' {1..200})
curl -s -X POST "$BASE/api/v1/advisors/register" \
  -H 'Content-Type: application/json' \
  -d "{\"did\":\"did:ocss:$LONG\",\"public_key_b64url\":\"x\"}"

{
  "error": "Bad Request",
  "message": "invalid_did: ocss: did:ocss slug is 200 bytes, exceeding the 128-byte bound",
  "code": 400
}

Per-account counts (advisory)

Phosra does not currently cap the number of children per family, webhooks per family, or active API keys per org. These are advisory — plan for reasonable numbers, and do not rely on the absence of a cap as a contract; a future release may introduce one.

Next steps