Troubleshooting

This page is organized by what you are seeing, not by error code. Find your symptom, read the cause, run the check. For the exhaustive code-by-code reference, see Errors.

Every check runs against the live sandbox at https://phosra-api-sandbox-production.up.railway.app — no key required for the reads below. Set it once:

bash

export BASE=https://phosra-api-sandbox-production.up.railway.app

First: decode any error in five seconds

Every error carries the same three fields. Read them in this order:

code — the HTTP status. 4xx is your request; 5xx is ours.
class — (OCSS routes only) the machine failure class. Branch on this.
failed_step — (403 standing failures only) the exact check that rejected you.

bash

# Pretty-print any error and its class
curl -s "$BASE/api/v1/providers/did:ocss:nope/connect" | python3 -m json.tool
# {
#   "error": "Not Found",
#   "message": "provider not found",
#   "code": 404,
#   "class": "not_found"
# }

Grab the X-Railway-Request-Id response header before you contact support — it lets us find your exact request in the logs.

bash

curl -s -D - -o /dev/null "$BASE/health" | grep -i x-railway-request-id

401 vs 404: which one should I be getting?

The two most-confused failures. They mean opposite things, and the API keeps them strictly separate so you always know which side the problem is on.

	`401 signature_invalid`	`404 not_found`
The route	exists, and requires you to prove who you are	may or may not exist — the resource behind it doesn't
What's wrong	your request signature (missing, malformed, wrong `key_id`)	the id in the path (a DID / rule / endpoint that isn't there)
Re-signing helps?	Yes — fix the signature and retry	No — the thing isn't there; a retry returns 404 forever
Leaks existence?	No — you get 401 before any lookup	Yes, deliberately: 404 means "genuinely absent," never a silent redirect to a nearby live resource

The trap: a signed route you call without a signature returns 401, not 404 — even if the path is nonsense. Authentication is checked before resource lookup, so a missing signature masks whether the resource exists at all.

bash

# No signature on a signed route -> 401 (the id is never even looked up)
curl -s -o /dev/null -w "%{http_code}\n" -X POST "$BASE/api/v1/enforcement-confirmations" \
  -H "Content-Type: application/json" -d '{}'
# 401
 
# An UNSIGNED read route with a bogus id -> 404 (resource lookup runs)
curl -s -o /dev/null -w "%{http_code}\n" "$BASE/api/v1/providers/did:ocss:nope/connect"
# 404

Decide in one question: does this route require a request signature? If yes and you're getting 401 → fix the signature (see below). If no, or your signature is already valid and you still get 404 → the id in your path is wrong; verify it character-for-character. A 404 is terminal — do not poll it back to life.

Symptoms

Class: signature_invalid

The route requires an RFC 9421 HTTP Message Signature and your request had none, had more than one, or the pair was malformed.

Common causes

You sent a bearer token where a request signature is required. Data-plane writes (rule writes, confirmations, consent) are signed, not bearer-authed.
You sent Signature without its matching Signature-Input (or vice-versa).
A proxy stripped or duplicated the headers.

Fix

Attach exactly one Signature-Input and one Signature header.
Sign with the key_id the census published for you — the exact did#kid echoed in your self-register response body.
Confirm your key is on the Trust List:

bash

# The signed Trust List carries an `entries` array — find YOUR DID in it.
# (The census serves `document` as a JSON *string* — parse it after verifying;
#  some older builds served an object instead, so a tolerant reader accepts both,
#  as the one-liner below does.)
curl -s "$BASE/.well-known/ocss/trust-list" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); doc=d['document']; doc=json.loads(doc) if isinstance(doc,str) else doc; e=doc['entries']; print(len(e),'entries'); print('mine:', any('did:ocss:acme-demo' in x.get('did','') for x in e))"
# e.g. 133 synthetic entries — the sandbox count changes as tests self-register.

Reproduce the failure (no signature → 401):

bash

curl -s -X POST "$BASE/api/v1/enforcement-confirmations" \
  -H "Content-Type: application/json" -d '{}'

Class: signature_invalid

Your signature is well-formed, but the key_id you signed with is not the one published on the Trust List for your DID.

Cause

You signed with did:ocss:you#some-kid but the census published did:ocss:you#2026-07 (the default is YYYY-MM).
You rotated your key and are signing with the old kid.

Fix — sign with the exact key_id from your registration response. When you self-register you can pin a bespoke kid; whatever the census echoes back is authoritative:

bash

curl -s -X POST "$BASE/api/v1/advisors/self-register" \
  -H "Content-Type: application/json" \
  -d '{"did":"did:ocss:acme-demo-'$(date +%s)'","public_key_b64url":"jDWZfB70DM8B3ZnPG8FQ0tnanqLgwJX4ZMr_E1Ugv3w"}' \
  | python3 -m json.tool
# -> "key_id": "did:ocss:acme-demo-...#2026-07"  <-- sign with THIS

Class: (house — no class field)

A validation error before the OCSS layer: a missing required field or a body that isn't valid JSON.

Fix

invalid_json: unexpected EOF → your JSON is truncated. Check quoting and that the body is complete.
did is required → include a did.
public_key_b64url is required → include your Ed25519 public key as a 43-char base64url string (no padding).

Minimal valid self-register:

bash

curl -s -X POST "$BASE/api/v1/advisors/self-register" \
  -H "Content-Type: application/json" \
  -d '{"did":"did:ocss:acme-demo-'$(date +%s)'","public_key_b64url":"jDWZfB70DM8B3ZnPG8FQ0tnanqLgwJX4ZMr_E1Ugv3w"}'

Class: malformed (standing check step d)

You wrote a rule with a rule_category that is not in the OCSS registry. The vocabulary is closed — the API rejects unknown slugs rather than coercing them.

Fix — use a registered category. The full list is the rule reference; common ones: addictive_pattern_block, dm_restriction, age_gate, content_block_title, infinite_scroll_block.

The same closed-vocabulary rule applies to age_band, harm_class, and method_class — an off-list value returns malformed, never a best-effort match.

Class: standing_failure or scope_failure — read failed_step.

Your request was cryptographically valid but you lack the authority for it. failed_step names the exact §6.2 check:

`failed_step`	What it means	Fix
`authority_binding`	No standing binds your DID to this child/subject	Present a consent attestation or grant for the subject first
`scope`	The category is outside your standing's granted scope	Write only in-scope categories, or widen the standing
`unregistered_slug`	The `rule_category` slug is not registered	Use a registered category
`band_exceeds_tier`	Your accreditation tier can't reach that enforcement band	Raise your tier, or write at a permitted band

For scope_failure, a consent attestation arrived for an app your DID does not operate — fix the app_ref so it names an app you run, or register that app.

Sandbox shortcut — a self-registered provisional DID can mint a TEST consent for itself over a sandbox test child, so a consent-first write completes without a Phosra-side roster edit:

code

POST /api/v1/sandbox/consent-attestations   (signed; PHOSRA_ENV=sandbox only)

Class: not_found

The sandbox connect endpoint resolves OAuth config for a synthetic provider fixture. A 404 means either the test DID isn't on the sandbox Trust List, or it is registered but has no oauth_connect config seeded.

Fix / diagnose

bash

# Synthetic fixture + configured -> 200 with authorize/token/profiles URLs
curl -s "$BASE/api/v1/providers/did:ocss:loopline/connect" | python3 -m json.tool
 
# Registered but NO connect config -> 404 (this is the load-bearing
# 'known-fixture-but-unconfigured' case, e.g. courier in the sandbox)
curl -s "$BASE/api/v1/providers/did:ocss:courier/connect"

A 404 here is never a silent substitution — the census will not redirect an unknown DID to a nearby live provider. Verify the DID string exactly.

Wrong-host check: a 404 on all DIDs (even did:ocss:loopline) usually means $BASE points at a non-census host — most often the control plane prodapi.phosra.com, which does not serve /providers/{did}/connect. For the documented evaluation flow, verify $BASE is the sandbox census, not prodapi. There is no public production hosted-routing endpoint today; see the production roadmap.

Class: (house — Conflict)

Self-register is create-only. It cannot overwrite an existing Trust List entry — that guards against a squatter rebinding another party's DID to a new key.

Fix

Registering for the first time? Pick a DID that isn't taken (the sandbox seeds 16+ reserved slugs like loopline, courier, beacon).
Rotating a key on a DID you already own? Self-register is not the path — use the key-rotation endpoint for your existing entry.

bash

# First call -> 200; identical DID again -> 409 Conflict
DID="did:ocss:dup-demo-$(date +%s)"
curl -s -o /dev/null -w "first:  %{http_code}\n" -X POST "$BASE/api/v1/advisors/self-register" \
  -H "Content-Type: application/json" \
  -d "{\"did\":\"$DID\",\"public_key_b64url\":\"jDWZfB70DM8B3ZnPG8FQ0tnanqLgwJX4ZMr_E1Ugv3w\"}"
curl -s -o /dev/null -w "second: %{http_code}\n" -X POST "$BASE/api/v1/advisors/self-register" \
  -H "Content-Type: application/json" \
  -d "{\"did\":\"$DID\",\"public_key_b64url\":\"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA\"}"
# first:  200
# second: 409

Class: replay

You reused an Idempotency-Key with a different payload than the first time it was seen. The key is permanently bound to its first body.

Cause — a retry regenerated part of the payload: a fresh timestamp, a new nonce, or a re-serialized object whose key order changed.

Fix

Build the payload once, freeze it, then attach the key.
On retry, resend the byte-identical payload with the same key.
A faithful replay is a success — it returns 200 with the original receipt bytes and header OCSS-Replay: original. Treat that as done, not as a duplicate.

Class: nonconformant

Distinct from signature_invalid. Your signature verified, but your deployment profile selects enforcement modes that fall outside the SUPPORTED set your Trust List entry declares (§9.4).

Fix — reconcile the two sets: either narrow the modes your profile selects to what you published as SUPPORTED, or update your Trust List entry's SUPPORTED set to include the modes you actually run. Never collapse this into a signature retry — the signature was fine.

Class: (house)

You exceeded the per-key / per-window rate limit. Every response carries the live counters — you never have to guess the quota.

Fix — read X-RateLimit-Reset (a Unix timestamp), sleep until then, retry once.

bash

# See your current window on any /api/v1 route (this GET needs no key).
curl -s -D - -o /dev/null "$BASE/api/v1/platforms" | grep -i x-ratelimit
# x-ratelimit-limit: 100
# x-ratelimit-remaining: 90
# x-ratelimit-reset: 1783311960

Only /api/v1/* responses carry these headers — the unauthenticated .well-known/ discovery reads are unmetered, so grep-ing them there returns nothing. Read your window off an API route.

Back off proactively when X-RateLimit-Remaining approaches zero rather than waiting for the 429.

When a provider rotates its key or a parent disconnects, there is a brief window where in-flight requests can race the change. The symptoms:

401 signature_invalid right after a key rotation — you signed with the old kid while the census already published the new one. Fix: re-fetch the Trust List, pick up the current kid, re-sign. Do not retry with the stale key.
404 not_found on a provider connect or profile right after a disconnect — the entry or endpoint was removed. Fix: treat 404 as terminal for that resource; do not poll it back to life. Re-run the connect ceremony to establish a fresh binding.
403 standing_failure (authority_binding) right after a consent withdrawal — the standing that authorized your write is gone. Fix: stop writing for that subject; a withdrawn consent is final until re-granted.

Why this is safe by design: the Trust List is served with Cache-Control: max-age=300 and a strong ETag. Poll it with If-None-Match so you notice a rotation within one cache window instead of discovering it via a failed write:

bash

ETAG=$(curl -s -D - -o /dev/null "$BASE/.well-known/ocss/trust-list" \
  | grep -i '^etag:' | tr -d '\r' | awk '{print $2}')
curl -s -o /dev/null -w "changed? %{http_code}\n" \
  -H "If-None-Match: $ETAG" "$BASE/.well-known/ocss/trust-list"
# 304 = unchanged, keep your cached keys; 200 = re-read, a key moved

Not an error. OCSS reads serve last-known-good and report staleness through a Receipt (§8.1 cl.4) rather than failing. There is deliberately no "stale" error class.

How to tell how fresh a read is

Cache-Control: public, max-age=300 → the artifact is guaranteed fresh for 300s.
The strong ETag changes the instant the artifact does — poll with If-None-Match and a 304 proves nothing moved.

If you need a definitely-current view, issue a conditional GET; a 200 (not 304) means you now hold the latest bytes.

500 returns the fixed body {"error":"Internal Server Error","message":"internal error","code":500} — deliberately no class and no cause text (we never leak internals onto the wire).

502 / 503 usually mean an upstream census is warming. Sandbox services auto-sleep to save cost and cold-start on the first request after idle.

Fix

Retry with exponential backoff (1s, 2s, 4s, 8s).
If a 500 persists, capture the X-Railway-Request-Id and contact [email protected] — it pins your exact request in the logs.

Class: (house)

You used the wrong HTTP method for the route (e.g. POST to a GET-only path). The response has an empty body and an Allow header listing the accepted method.

bash

curl -s -D - -o /dev/null -X POST "$BASE/api/v1/providers/did:ocss:loopline/connect" \
  | grep -i '^allow:'
# allow: GET      (read routes also advertise HEAD)

Fix — switch to the method in Allow. Double-check you're hitting the intended route; a trailing-slash or path-segment typo can land you on a different handler.

Still stuck?

Confirm the census is up

bash

curl -s "$BASE/health"          # {"status":"ok"}

Confirm your identity is on the Trust List

bash

curl -s "$BASE/.well-known/ocss/trust-list" | python3 -m json.tool | head

3
Capture the request id and reach out
Grab X-Railway-Request-Id from the failing response and email [email protected] with the request id, the code, the class, and (if present) the failed_step.

Error reference

The complete status-code and error-class tables, every field documented.

Authentication

API keys, WorkOS sessions, and RFC 9421 request signing.

Troubleshooting

First: decode any error in five seconds

401 vs 404: which one should I be getting?

Symptoms

401 — 'exactly one Signature-Input and one Signature header are required'

401 — 'unknown key_id' / signature verifies locally but the census rejects it

400 — 'did is required' / 'public_key_b64url is required' / 'invalid_json'

400 — 'unregistered rule_category slug: the OCSS rule vocabulary is closed'

403 — signature is valid but the write is refused

404 — 'provider not found' on /providers/{did}/connect

409 — 'did_already_registered' on self-register

409 — 'replay' on a write I retried

422 — 'nonconformant': signature valid but the profile is rejected

429 — 'Too Many Requests'

Disconnect / rotation races — a call that worked a moment ago now 401s or 404s

A read looks stale — am I getting old data?

500 / 502 / 503 — a server error

405 — 'Method Not Allowed' with an empty body

Still stuck?

Error reference

Authentication