All documentation

Best Practices

Production guidance for keys, idempotency, and enforcement.

Download Markdown
GuidesAPI ReferenceCode ExamplesBest Practices

Best Practices (Production Integrations)

Recommendations for secure, reliable production integrations with Naiza.

Security

  • Never expose long-lived API keys in browsers or mobile clients
  • Prefer Web SDK tokens for browser integrations (Web SDK API)
  • Rotate keys on a schedule and immediately after suspected compromise
  • Treat webhook signingSecret like a password (store encrypted, restrict access)

Request Safety

  • Always use HTTPS in production
  • Set timeouts on outbound HTTP clients
  • Validate responses before acting on decisions (schema drift should fail closed in your domain logic)

Rate Limits and Quotas

  • Respect 429 responses with backoff
  • Track quota headers when present (Rate Limiting)
  • Avoid polling loops; prefer webhooks for asynchronous completion signals

Error Handling and Retries

  • Do not retry 4xx except when explicitly safe (for example network disconnect before reading body)
  • Retry 429 and 5xx with jittered exponential backoff
  • Use Idempotency-Key for feedback writes (Feedback API)

Observability

  • Propagate x-request-id / x-correlation-id from your edge to Naiza requests when available
  • Log correlationIds from decision responses for support investigations
  • Alert on sustained 401, 429, and 5xx spikes

Data Minimization

  • Send only fields needed for fraud decisions
  • Avoid sending full PANs, CVVs, or government IDs unless you have a contractual/legal basis

Rollout Guidance

  • Start with shadow mode (log-only) in a single flow, then enforce
  • Roll out by percentage of traffic or by geography
  • Keep a documented rollback path (feature flags, routing rules)

Need Help?

If you have questions about integrating Naiza or need assistance with your implementation, our team is here to help.

Contact Support