---
title: "Best Practices (Production Integrations)"
description: "Production guidance for keys, idempotency, and enforcement."
collection: "guides"
slug: "best-practices"
url: "https://naiza.ai/docs/guides/best-practices"
markdown: "https://naiza.ai/docs/guides/best-practices.md"
full_docs: "https://naiza.ai/docs.md"
product: "Naiza"
base_url: "https://api.naiza.ai/api/v1"
---

# Best Practices (Production Integrations)

> Production guidance for keys, idempotency, and enforcement.

## Table of contents

- [Security](#security)
- [Request Safety](#request-safety)
- [Rate Limits and Quotas](#rate-limits-and-quotas)
- [Error Handling and Retries](#error-handling-and-retries)
- [Observability](#observability)
- [Data Minimization](#data-minimization)
- [Rollout Guidance](#rollout-guidance)

## Security

- Never expose long-lived API keys in browsers or mobile clients
- Prefer Web SDK tokens for browser integrations ([Web SDK API](https://naiza.ai/docs/api-reference/websdk.md))
- 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](https://naiza.ai/docs/api-reference/rate-limiting.md))
- 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](https://naiza.ai/docs/api-reference/feedback.md))

## 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)

## Related documentation

- [Overview](https://naiza.ai/docs/guides/overview.md) — Base URL, authentication, decision types, risk scores, and rate limits.
- [Getting Started](https://naiza.ai/docs/guides/getting-started.md) — Make your first Naiza API call and verify your integration.
- [Tenant Onboarding](https://naiza.ai/docs/guides/tenant-onboarding.md) — Create tenants, invite operators, and configure webhooks.
- [Web SDK — Install & CDN](https://naiza.ai/docs/guides/web-sdk-install.md) — Install the browser SDK via CDN, self-host, and verify ingest.
- [Quick Start](https://naiza.ai/docs/guides/quick-start.md) — Common operations for events, decisions, lists, and feedback.
- [Event Monitoring](https://naiza.ai/docs/guides/event-monitoring.md) — Model product events and turn rule outcomes into decisions.
- [AML Integration](https://naiza.ai/docs/guides/aml-integration.md) — Screen customers and counterparties against AML watchlists.
- [Integration Examples](https://naiza.ai/docs/guides/integration-examples.md) — Node.js, Python, cURL, and webhook handler examples.

---

*Source: [https://naiza.ai/docs/guides/best-practices](https://naiza.ai/docs/guides/best-practices) · Full docs: [https://naiza.ai/docs.md](https://naiza.ai/docs.md)*