Error Codes & Troubleshooting

Every PasskeyBridge function answers errors as JSON. The shared helper writes {"error": "<human-readable message>"} and adds fields when the endpoint has more to say:

{
  "error": "Temporal window exceeded",
  "detail": "Capture duration 140ms exceeds maximum 100ms",
  "code": "NF08_TEMPORAL_WINDOW_EXCEEDED"
}

error is always present. code appears only where the endpoint defines a structured code (see the table two sections down). Other endpoints add details (an array of validation messages), issues (path and code pairs, no values), reason, hint, upgrade_url or billing_url.

Two surfaces differ. SCIM uses the RFC 7644 envelope with schemas, detail, status and sometimes scimType. The hosted passkey relying party answers {"error":"bad_request","issues":[{"path":"rp_id","code":"invalid_string"}]} and never echoes a submitted value.

Read the headers first. Auth and quota refusals carry x-pb-reason, which is stable and machine-readable while the message text is not. Every response proxied through api.passkeybridge.io also carries x-pb-debug-id, the Cloudflare ray id; quote it in a support ticket and it matches the access log one to one.

Handle errors in this order: HTTP status, then x-pb-reason, then code, then the error string.

A 503 on a tenant lookup is deliberately distinct from a 404: the tenant may well exist and the query failed. Retry a 503; do not retry a 404.

Signal ingest has the largest error surface on the platform, and its refusals are ordered. Knowing the order tells you what already passed.

1. Method and body: 405 Method not allowed, 413 Request body too large, 400 Invalid request body, 400 Invalid JSON body.
2. Schema: 422 Payload validation failed with a details array, one entry per field, for example event_type: Signal type contains invalid characters.
3. subject_ref: 400 with x-pb-reason: invalid-subject-ref when the value is not 1 to 128 printable ASCII characters, or looks like an email address or a phone number.
4. Tenant: 400 Missing tenant ID in path or x-pb-tenant-id header, 503 Tenant lookup failed, 404 Unknown tenant, 403 Tenant is suspended.
5. Rate limit: 429 from the per-IP layer, then the per-tenant plan layer.
6. Credential: 401 Missing x-pb-api-key header, 401 Invalid API key, 403 API key missing 'ingest' scope, 403 Tenant ID header does not match path tenant. In test mode: 401 Test mode requires authorization header, 401 Invalid auth token, 403 Tenant not found or user is not an admin.
7. Signature: 401 Webhook signature required for this tenant (x-pb-signature header missing), 401 Invalid webhook signature.
8. Allotment: 429 Sandbox and test-mode signal limit reached (1000 per 30 days). Use a live (non-sandbox) API key for production traffic., 429 Starter plan monthly signal limit reached (100). Upgrade at /pricing to keep processing signals., 402 Monthly signal allotment reached (100) while your subscription is unpaid.
9. Persistence: 502 Failed to persist signal event, 500 Usage lookup failed.

A `200` can still report trouble. status: "warning" means one or more playbook actions failed; actions_failed_count says how many, and the Events tab shows each action's status. result: "no_matching_playbook" means the signal was stored and no playbook matched its event type.

The correlation id is generated by the function. An inbound x-pb-correlation-id header is not read on this path, so quote the correlation_id from the response body rather than the one you sent.

Not every function is action-routed. Signal ingest routes on event_type, SCIM and support are REST-shaped, and DID resolution and entropy receipts are GET only. Sending {"action": ...} to those does nothing.

Check code before parsing error. Where there is no code, the pair of HTTP status and x-pb-reason is the stable signal.

Three different 429 bodies exist, and they mean different things.

Per-IP and per-tenant plan limit. Two layers, an in-isolate counter and a database-backed one, both keyed by function, tenant and a keyed digest of the source IP.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Layer: l2

{ "error": "Too many requests. Please retry after 60 seconds.", "limit": 300, "remaining": 0, "layer": "l2" }

X-RateLimit-Layer is l1 when the in-isolate counter refused and l2 when the distributed counter did. X-RateLimit-Degraded: true means the distributed check could not be consulted, so the verdict was made per isolate.

Known reporting defect. The pre-authentication refusal on signal ingest uses the simple helper, which hard-codes X-RateLimit-Limit: 60 while the limit actually applied is 1,200 per minute per IP. The refusal is correct; the header understates it. Use Retry-After, which is right in every shape.

Per-tenant quota. A different body and its own reason header:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 0
X-RateLimit-Scope: minute
x-pb-reason: quota-exceeded

{ "error": "tenant_quota_exceeded", "scope": "minute", "limit": 3000, "retry_after_seconds": 60 }

Allotment caps. Sandbox keys and x-pb-test-mode requests share 1,000 signals per rolling 30 days and refuse with x-pb-reason: sandbox-cap. Starter tenants refuse past 100 signals in the calendar month with an upgrade message and no reason header.

Cloudflare. A single IP over 1,200 requests per minute per data centre is blocked at the edge for 60 seconds. That response never carries x-pb-reason, which is how you tell it from an application refusal.

Honour Retry-After as the minimum wait. The window is fixed, so retrying sooner earns another 429. Full detail is in Rate limits and quotas.

The shared auth module stamps a reason header on every refusal. Key off the header.

Endpoints with their own inline check word it differently for the same condition:

{ "error": "Missing x-pb-api-key header" }              // 401, shield-ingest, shield-vc-verify
{ "error": "Invalid or inactive API key" }              // 401, shield-spatial-bind
{ "error": "API key lacks 'spatial' scope" }            // 403, shield-spatial-bind
{ "error": "API key missing 'vc_verify' scope" }        // 403, shield-vc-present
{ "error": "Invalid SCIM bearer token" }                // 401, shield-scim
{ "error": "API key does not have 'scim' scope" }       // 403, shield-scim
{ "error": "Unauthorized—missing Bearer token" }        // 401, shield-a2a-handshake
{ "error": "Forbidden—not a member of this tenant" }    // 403, shield-a2a-handshake
{ "error": "Only admins can create agent delegates" }   // 403, shield-agent-delegate
{ "error": "Unknown or revoked agent" }                 // 403, agent verify
{ "error": "Agent delegation has expired" }             // 403, agent verify
{ "error": "Agent not authorized for scope: ingest" }   // 403, agent verify

If a `401` surprises you, check three things. The header is x-pb-api-key, not Authorization (SCIM and Okta hooks are the two exceptions, and they want the key as a bearer token). The key starts with pb_live_ or pb_test_. The key has not been revoked in Dashboard > API keys, and x-pb-tenant-id names the tenant that owns it.

A `403` with no `x-pb-reason` on a proxied call is tagged upstream-auth by the worker. That means the function refused and did not classify the refusal itself.

Replay protection. initiate, attest, negotiate and renew each require a fresh nonce and a timestamp. status and lookup require neither. invalidate is service-to-service only and is refused with 403 Forbidden—service authentication required for anyone else.

REPLAY_DETECTED covers three distinct failures, so read the error string alongside the code: a nonce already consumed (Nonce already consumed—replay detected), a mutating action with no nonce (Replay protection required: nonce is mandatory for '<action>' action), and a timestamp outside the 5-minute window (Clock drift <n>ms (client ahead) exceeds 300000ms tolerance). Only the first is an actual replay; the other two are client bugs.

mTLS diagnostics name each side separately:

{
  "error": "Certificate verification failed",
  "code": "MTLS_FAILED",
  "initiator_cert": "Presented certificate fingerprint does not match any pinned certificate",
  "responder_cert": "No certificate pins configured (mTLS not enforced)"
}

Inspecting a negotiation. action: "status" returns the current state, the combined trust coefficient, the derived limits, cache_valid and, when re-attestation is needed, re_attest_reason.

Status list reads. GET /v1/shield-vc-status?issuer=<did>&type=statuslist answers 400 for a malformed issuer DID. An issuer that is well-formed but whose slug matches no tenant also answers 400 with the same message, because the lookup and the format check share one failure path. A single credential lookup for an unknown id answers 200 with status: "unknown" rather than 404.

Expiry. expiration_days defaults to 90 and is capped by the registered schema's maximum lifetime when one exists, so a credential can come back with a shorter life than requested.

Issuance latency. Post-quantum signing dominates the issue path. The response carries latency_ms so you can see it per credential.

A failed verification answers `403` by design. When the anomaly score reaches 0.45 the response is 403 with status: "anomaly_detected", passed: false, the score and the reasons. A clean verification is 200 with status: "verified". Both outcomes store a binding row, so both appear in Dashboard > Device bindings.

Anomaly scoring adds 0.8 for a device identifier that does not match the baseline, 0.5 when the EMI and thermal digests are both identical to the baseline (an exact replay), and 0.4 when the network jitter digest is identical (a jitter replay). A fresh capture from the enrolled device scores 0.

1. Quote the correlation id from the response. Signal ingest generates its own correlation_id in the shape pb-<timestamp>-<random> and returns it. It threads through the trust engine, the intelligence worker and the audit log. An inbound x-pb-correlation-id header is not read on the ingest path.

2. Quote the debug id for anything proxied. Every response through api.passkeybridge.io carries x-pb-debug-id, the Cloudflare ray id.

3. Confirm your headers reach the edge. POST https://api.passkeybridge.io/v1/_debug/echo answers without calling any function and reports what arrived, including whether a key was present and the first 8 characters of it. If the key reached the edge and you still get 401, the tenant id is the usual culprit.

4. Know which headers the worker forwards. Eighteen names are copied onto the upstream request, x-pb-signature, x-shield-signature, dpop and if-none-match among them, so a signed ingest request, a DPoP proof and a conditional status-list read all reach the function through the public host. Anything outside that list is dropped before the function runs; the full list is in Edge-first signal verification.

5. Read the audit log. Dashboard > Audit log records every significant action with result set to success, partial or failure, the actor type (user, api_key, system) and the resource. Filter by resource type and id to trace a lifecycle.

6. Read the event row. Dashboard > Events shows the decision path time, the full response time, the playbook result and every action with its own status and latency. Test-mode and sandbox events carry a Test badge and are excluded by the live filter.

7. Common integration mistakes.

• Sending Authorization: Bearer pb_live_... to a function that wants x-pb-api-key. SCIM and Okta hooks are the only two that want the key as a bearer token.
• Omitting x-pb-tenant-id. Most key-authenticated endpoints need it, and the ones that read tenant_id from the body say so.
• Calling the Supabase functions host directly and getting 403 Direct access denied.
• Assuming every function is action-routed. Signal ingest routes on event_type; SCIM and support are REST; DID resolution and entropy receipts are GET only.
• Calling negotiate before attest, or reusing a nonce.
• Treating a 200 with status: "warning" as a clean result.
• Expecting x-pb-scope-warning: legacy-unscoped to be harmless: it means the key predates scope enforcement and should be reissued.