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. Two surfaces fail differently, so check you are on the right one. Census errors (everything with a code + class in the body) are below under Symptoms. Failures from your own Link route — the handler that @phosra/link mounts under /api/phosra/link/* — have no message and no class and are under Phosra Link symptoms.

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:

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.

# 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.

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.

# 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

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

Class: signature_invalidThe 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:

# 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 entries  — the live count grows as providers accredit; yours will differ.

Reproduce the failure (no signature → 401):

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

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

Class: signature_invalidYour 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:

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

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

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:

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"}'

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

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.

403 — signature is valid but the write is refused

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:

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

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

Class: not_foundThe connect endpoint resolves OAuth config for an accredited provider. A 404 means either the DID isn’t on the Trust List, or it’s registered but has no oauth_connect config seeded.Fix / diagnose

# Accredited + 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
# 'accredited-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. Verify $BASE is an OCSS census (the sandbox host, or your assigned production census host — see Production Accreditation), not prodapi.

409 — 'did_already_registered' on self-register

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.

# 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

409 — 'replay' on a write I retried

Class: replayYou 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.

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

Class: nonconformantDistinct 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.

429 — 'Too Many Requests'

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.

# 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.

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

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:

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

A read looks stale — am I getting old data?

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 / 502 / 503 — a server error

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 developers@phosra.com — it pins your exact request in the logs.

405 — 'Method Not Allowed' with an empty body

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.

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.

Phosra Link symptoms

These come from your own Link route, not from the census, so none of the checks above apply to them. The full catalogue is Phosra Link route errors.

Any Link failure at all — where do I even look?

Start here before anything else on this list.Link’s JSON envelope is {"error":{"code","correlation_id"}} — no message, no class. A failed callback is worse: it renders an HTML page (“We couldn’t finish connecting”) with no code and no correlation id at all. Neither surface tells you what went wrong, deliberately.The cause exists in exactly one place: the onDiagnostic hook on your Golden server config. It is optional, so a config copied from a quickstart often omits it — and then a failure is genuinely unrecoverable information.

const server = await createGoldenLinkServer({
  credential, database, authenticate, children, policy,
  onDiagnostic: (d) => console.error(JSON.stringify({
    event: "phosra_link_diagnostic",
    operation: d.operation,
    subcode: d.subcode,
    lifecycleSubstep: "lifecycleSubstep" in d ? d.lifecycleSubstep : undefined,
    retryable: d.retryable,
    correlationId: d.correlationId,
    causeClass: d.causeClass,
  })),
})

Read subcode (which step), lifecycleSubstep (which durable substep), and causeClass (whose bug). Log correlationId — it is the only identifier tying the failure to anything, and the one to quote to support. Full field reference: onDiagnostic.

403 ORIGIN_REJECTED — but I checked, the origins match

Two different gates return this code, and the one that catches most people has nothing to do with the Origin header.

A missing Origin header is refused exactly like a mismatched one. The check is a strict inequality against your credential’s application.origin, and a request with no Origin is not equal to it. curl, Postman, and every server-side smoke test send none by default — so they all 403 while your credential is perfectly correct. Add it by hand:
curl -i -X POST https://app.example/api/phosra/link/sessions \ -H "Origin: https://app.example" -H "Content-Type: application/json" \ -d '{"platform_did":"did:ocss:notflix","child_ref":"…","return_to":"/family"}'
The request URL’s own origin is checked on every method, before any path or method dispatch, and it is derived from Host / X-Forwarded-Host. A proxy or container that does not forward the public host 403s everything — including GET …/link/callback, which is a top-level navigation with no Origin header, so gate (1) never even runs there.

Which one am I on? A 403 on the GET callback is always gate (2) — fix the forwarded host, not your CORS config. A 403 only on POST …/link/sessions from a tool is gate (1).GET …/link/sessions/{id} (status) is the only operation exempt from the header gate, which makes it a usable liveness probe.Then confirm the pinned origin:

node -e 'const c=process.env.PHOSRA_CREDENTIAL.replace(/^phosra_cred_v3\./,"");
console.log(JSON.parse(Buffer.from(c.split(".")[0],"base64")).application)'

A production credential can never work on http://localhost — production credentials are canonical-HTTPS-origin only. Sandbox credentials may carry http://localhost[:port] / http://127.0.0.1[:port].

The Link dialog says 'Try again' on a failure that can never succeed

Your createSession adapter is throwing away the error code.The dialog has an honest branch for permanent configuration faults — “This app isn’t set up for this address”, with Close as the only button. It selects that branch only when the rejection your adapter throws carries a string code equal to "ORIGIN_REJECTED" (directly, or up to four cause links deep). A bare throw new Error("Unable to start Phosra Link") carries no code, so it falls through to the generic retryable copy and a Try again button that cannot work.Fix — lift error.code off the response body and attach it to what you throw. The complete adapter is in ORIGIN_REJECTED.

401 UNAUTHENTICATED on the Link callback — only in local dev

Cookies ignore the port. Every app on http://localhost shares one cookie jar, so if your provider app and the platform app use the same session cookie name, signing in at the platform evicts the parent’s session on your provider. The parent finishes the platform leg, the browser returns to GET …/link/callback, your authenticate(request) adapter finds nothing, and the route answers 401.Nothing about your Link configuration is wrong. Fix — give each app a distinct cookie name locally:

WORKOS_COOKIE_NAME=custo-wos-session     # provider app
WORKOS_COOKIE_NAME=notflix-wos-session   # platform app

LINK_OPERATION_FAILED and I have no idea which step broke

This is the catch-all — roughly eighty internal rejections collapse into it, and it carries no cause by contract. Read the status first, then the diagnostic.

Status	Means
`409`	A durable state conflict. Not retryable
`502`	An adapter returned a shape the SDK will not accept (`children.resolve`, `policy.resolve`, or the platform directory), or an authority mismatch. Not retryable
`503`	A durable step was unavailable (evidence, finish, rules, delivery). Retryable

Then read lifecycleSubstep from onDiagnostic. The two that bite first:

save_connection / record_evidence — your database refused a write. Almost always a package schema migration that was not re-run after an SDK upgrade. Run link.migrate() (or apply printLinkSchema()), then retry.
deliver_rules — delivery to the platform receiver failed. Check the receiver’s allowlist for your provider DID.

And read causeClass: anything starting golden_directory_ is a trust/directory problem, not your adapter. type_error and error mean an exception escaped your own adapter code.

404 / 410 LINK_SESSION_UNAVAILABLE after the parent hits Back

Terminal, and expected. 404 means the ceremony row is gone; 410 means it expired or was already spent — including a callback whose state matches no pending row. A parent who completes a connection and then presses Back re-opens a spent callback URL and produces exactly this.Fix — never re-open a callback URL and never retry it. Start a fresh ceremony. Surface the current connection state (GET …/link/sessions/{id}) rather than an error; the connection itself may well have succeeded.

Every /api/phosra/* route returns 503 PHOSRA_NOT_READY

That is the platform SDK (@phosra/gatekeeper), not the Link route. Bootstrap has not completed, and every protocol route answers the same opaque 503 until it does.Do not guess — GET /api/phosra/status names the outstanding precondition directly, and every one of them is documented with its fix on Readiness.The two that are invisible from your own code:

Your own directory row must already exist and match exactly: directory_version: 1, name equal to your credential’s display name, and authorize/par/token/profiles URLs on your application origin. Missing row → PLATFORM_BOOTSTRAP_DIRECTORY_FAILED. Publish it with PATCH /api/v1/platforms/{did}/connect.
The census’s operating router must itself resolve active and accredited. If it does not, no platform can boot on that census — and nothing in your configuration can fix it. That surfaces as PLATFORM_BOOTSTRAP_TRUST_FAILED; report it to the census operator.

Still stuck?

Confirm the census is up

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

Confirm your identity is on the Trust List

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

Capture the request id and reach out

Grab X-Railway-Request-Id from the failing response and email developers@phosra.com with the request id, the code, the class, and (if present) the failed_step.For a Phosra Link failure there is no X-Railway-Request-Id — the route is yours, not the census’s. Send the correlationId your onDiagnostic hook logged, plus operation, subcode, lifecycleSubstep, and causeClass. That set is the whole picture; the HTTP body carries nothing else.

Error reference

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

Authentication

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

Get Started

Concepts

Guides

Cookbook

Partner Integration

Phosra Link (secret-free)

OCSS Conformance

Platform

First: decode any error in five seconds

401 vs 404: which one should I be getting?

Symptoms

Phosra Link symptoms

Still stuck?

Error reference

Authentication

​First: decode any error in five seconds

​401 vs 404: which one should I be getting?

​Symptoms

​Phosra Link symptoms

​Still stuck?

Error reference

Authentication

First: decode any error in five seconds

401 vs 404: which one should I be getting?

Symptoms

Phosra Link symptoms

Still stuck?