Errors & troubleshooting

Check HTTP status first, then the JSON status / reason fields. Most integration issues are credential, scope, or flow-state problems — verify those before contacting support.

Status codes

2xx—
Success. 201 is common for flow creation; 200 for ping and reads.
4xx—
Client error — fix headers, body, or flow id. See tables below.
5xx—
Server error — retry with backoff; check status.pasby.africa.

Plain-text middleware errors

HTTP	Message	Fix
401	`An api key is needed to access our services.`	Add `x-api-key`
400	`App secret missing in headers.`	Add `x-access-secret` on v2 routes
429	Rate limit message	Back off; max ~100 req/min/IP

Validation errors (HTTP 400)

Zod-style JSON array, e.g. invalid NIN or missing claims:

[
  {
    "code": "too_small",
    "minimum": 11,
    "path": ["body", "user"],
    "message": "Invalid nin identifier"
  }
]

Symptom	Fix
Missing claims	Pass `claims` array — see Claims reference
Seeds out of range	Use integer 1–10 on wildcard routes
Invalid webhook URL	Use HTTPS `host` on sign / document routes

API error envelope

{
  "status": "handled",
  "reason": "Human-readable explanation",
  "type": "authorization_error",
  "code": 400,
  "helper_url": "https://docs.pasby.africa/docs/reference/errors",
  "body": {}
}

`type`	Typical cause
`authorization_error`	Invalid credentials
`param_error`	Bad request parameters
`session_cancel`	User cancelled — handle in UI
`session_expiry`	Flow or token expired — restart flow

OIDC errors

Message	Fix
Handshake invalid or expired	Repeat OIDC quickstart; fresh `handshake`
Challenge verification failed	Use PKCE verifier from same session
Access token invalid or expired	Shorter session TTL; re-run exchange

Flow troubleshooting

Symptom	Check
Flow never completes	Correct `request` id; user finished on device — Flow lifecycle
Empty `claims` on ping	Not complete yet; or user denied fields
Cannot decrypt claims	Communication keys