Docs/API reference/Authentication and errors
Authentication and errors
Authenticate backend requests and respond to failures without exposing credentials or retrying unsafe operations.
Authentication#
Send your backend API key in x-loyfin-api-key when creating issuance or redemption sessions. Business account-management endpoints use a Privy access token. Private checkout reads and customer authorization use the opaque claim token from the checkout URL. Public reads do not expose authorization signatures.
Never put an API key in browser code or a public repository. Treat checkout URLs and webhook secrets as credentials. Display a safe message to customers; keep diagnostic details in access-controlled backend logs.
Respond to HTTP errors#
| Status | Handling |
|---|---|
| 400 / 422 | Check the request fields and signing mode. Correct validation failures before retrying; do not change a previously authorized operation without reconciling it. |
| 401 | Check credentials and key rotation. Do not repeatedly retry with the same invalid key. |
| 403 | Check wallet ownership, signing enablement, allowed program IDs, and amount limits. |
| 404 | Check the endpoint, chain, and identifier. A checkout UUID differs from a numeric operation ID. |
| 409 | Reconcile the existing nonce or conflicting operation. A fresh nonce is not a safe automatic retry. |
| 429 | Honor Retry-After when supplied. Check whether the daily signing limit has been reached before retrying. |
| 5xx / network interruption | The result may be uncertain. Retain the exact payload and use bounded exponential backoff with jitter. |
Rate limits and recovery#
Limits depend on the endpoint and deployment. API signing also enforces the configured account limits; rotating keys does not reset account-wide daily usage. Avoid concurrent retry loops. Follow Retries and reconciliation before releasing points or creating a replacement. Use OpenAPI for each endpoint’s current request and response schema.