Operations
Errors & troubleshooting
Diagnose key, origin, quota, telemetry, webhook, and SAML failures without accidentally approving an operation.
On this page
Error envelope
json
{
"success": false,
"statusCode": 403,
"message": "Origin is not allowed for this site",
"timestamp": "2026-10-14T12:00:00.000Z"
}Validation errors may also include errors. SDK exceptions preserve the status and response. Report request context and timestamps in your own logs without recording server keys, webhook secrets, raw cards, or credentials.
Status codes
| Status | Likely cause | Recovery |
|---|---|---|
| 400 | Malformed JSON, invalid context, expired token, replayed challenge. | Fix the request; refresh expired telemetry or challenge. |
| 401 | Invalid/missing site key, secret, or access token. | Check selected site credentials; sign in again for management. |
| 403 | Origin, role, plan gate, suspended access, or site cap. | Correct the origin/access/plan configuration. |
| 409 | Idempotency key reused with a different payload. | Retry the original payload or assign a key to the new operation. |
| 413 | HTTP body exceeds route limit. | Bound telemetry and batch sizes. |
| 429 | Monthly quota or transient engine rate limiting. | Inspect the message; retry bounded transient errors or resolve quota. |
| 500 | Unexpected server failure. | Keep operation pending; retry idempotently and investigate. |
| 503 | Scoring unavailable, receipt busy/ownership change, or unconfigured payment service. | Retry scoring idempotently; do not approve on failure. |
Browser collection fails
- Check the public site key belongs to the site being viewed.
- Compare window.location.origin to the site’s exact allowedOrigins list.
- Check CSP connect-src permits the API and script-src permits the hosted SDK when used.
- Confirm buildRequest runs in the browser after initialization, not during SSR.
- Forward full telemetry to the backend; expired tokens need fresh collection.
Webhook verification or delivery fails
- Read raw request bytes before JSON middleware and use the webhook signing secret, not the site server secret.
- Confirm the server clock is within the verifier tolerance.
- Use a public HTTPS port-443 receiver with publicly resolvable addresses.
- Return 2xx only after durable acceptance; redirects are not followed.
- Check dashboard delivery status and recent attempts. A test needs enabled configuration and an existing recorded event.
SAML sign-in fails
- Confirm Enterprise access, enabled configuration, and a currently valid IdP certificate.
- Use the exact issuer and ACS URL reported by the workspace configuration.
- Require a signed assertion, even when the IdP also signs the response.
- Start from the workspace login URL; unsolicited responses do not have the expected state.
- Match the assertion email to an existing active team membership.
- Check browser cookies and clock skew; expired state or one-use codes require a new sign-in.