Skip to main content

​
Best practices

​
Session management

​
Do

  • Use Idempotency-Key for create and renew to avoid duplicate orders on retries.
  • Terminate sessions when done: POST /sessions/{session_id}/terminate.
  • Monitor usage via GET /sessions/{session_id}/usage; act when usage is high (e.g. >80%).
  • Limit concurrency when creating many sessions (e.g. semaphore or queue).

​
Avoid

  • Leaving sessions active indefinitely without cleanup.
  • Rotating on a fixed schedule regardless of success/failure — prefer rotating on errors (403, 429, captcha) or when telemetry recommends it.
  • Hardcoding api_key or api_secret; use environment variables or a secret manager.
  • Skipping telemetry — report success and errors so the system can suggest when to rotate.

​
Performance

PracticeDescription
Reuse sessionsOne session for many requests instead of creating per request
Smart rotationUse telemetry recommendation (e.g. rotate_now) rather than blind timed rotation
Report telemetryEnables better health and rotation advice
Cache productsProduct list changes infrequently; cache 5–10 minutes
Connection poolUse HTTP client connection pooling
Respect rate limitsRead X-RateLimit-* headers and throttle to avoid 429

​
Security

PracticeDescription
Env for secretsStore API key/secret in env or secret manager
HTTPS onlyAll requests to https://api.nexalayer.net/v1
Token refreshIf using JWT, refresh before expiry
Monitor usageWatch for unexpected API or session usage

​
Example: rotate on recommendation

After each request, report the outcome and optionally rotate when the API suggests it: 
# After request
event_type = "success" if resp.status_code < 400 else "http_error"
report = requests.post(
    f"{BASE}/sessions/{session_id}/report-event",
    json={
        "event_type": event_type,
        "status_code": resp.status_code,
        "latency_ms": latency_ms,
        "target_host": host,
    },
    headers=headers
).json()["data"]
rec = report["session_health"]["recommendation"]
if rec == "rotate_now":
    requests.post(
        f"{BASE}/sessions/{session_id}/rotate",
        json={"reason": f"http_{resp.status_code}"},
        headers=headers
    )
Next: Architecture, Errors.