Production Readiness

Use this guide before shipping a third-party integration. It covers auth expectations, quota semantics, safe retry policy, and the minimum operational checks needed for a production launch.

Check status endpoint Errors & limits

Authentication expectations

The API is API-key only.
Authenticated content API access requires a Business-enabled personal workspace.
Use GET /api/v1/status as the supported auth and entitlement probe during startup and health checks.
Keep API keys on your server or in a trusted backend worker. Do not expose them in browser bundles or mobile client storage.

Quota and throttle semantics

Per-minute throttles return 429 Too Many Requests with Retry-After.
Daily quota exhaustion returns 429 Quota Exceeded.
The daily quota window resets at 00:00 UTC.
Once a request is authenticated and entitled, downstream endpoint failures can still consume quota budget.
Use the limits object from /api/v1/status to budget request volume for the active key.

Retry policy

Recommended handling

text

409 insufficient_stock  -> adjust constraints, lower limit, or retry later
429 Too Many Requests -> back off using Retry-After plus jitter
429 Quota Exceeded    -> stop until the next UTC quota window or upgrade
503 / 5xx             -> retry with capped exponential backoff and jitter
400 / 401 / 403       -> do not retry until input or auth state changes

The background refill triggered on stock shortfall is best-effort. It does not guarantee that the exact request will succeed if you retry immediately.

Launch checklist

Probe /api/v1/status during deploy or worker startup.
Store keys in a secrets manager and rotate them by environment.
Log request outcomes, rate-limit events, and 409 shortfalls without logging credentials.
Persist your own delivery-scope identifiers so deliveryKey is stable across retries.
Cache or persist served question IDs if you need stronger no-repeat guarantees than a single delivery scope.
Alert on sustained 429 or 503 rates before they become a customer-facing outage.

Authentication expectations

The API is API-key only.

Authenticated content API access requires a Business-enabled personal workspace.

Use GET /api/v1/status as the supported auth and entitlement probe during startup and health checks.

Keep API keys on your server or in a trusted backend worker. Do not expose them in browser bundles or mobile client storage.

Quota and throttle semantics

Per-minute throttles return 429 Too Many Requests with Retry-After.
Daily quota exhaustion returns 429 Quota Exceeded.
The daily quota window resets at 00:00 UTC.
Once a request is authenticated and entitled, downstream endpoint failures can still consume quota budget.
Use the limits object from /api/v1/status to budget request volume for the active key.

Retry policy

Recommended handling

text

409 insufficient_stock  -> adjust constraints, lower limit, or retry later
429 Too Many Requests -> back off using Retry-After plus jitter
429 Quota Exceeded    -> stop until the next UTC quota window or upgrade
503 / 5xx             -> retry with capped exponential backoff and jitter
400 / 401 / 403       -> do not retry until input or auth state changes

The background refill triggered on stock shortfall is best-effort. It does not guarantee that the exact request will succeed if you retry immediately.

Launch checklist

Probe /api/v1/status during deploy or worker startup.

Store keys in a secrets manager and rotate them by environment.

Log request outcomes, rate-limit events, and 409 shortfalls without logging credentials.

Persist your own delivery-scope identifiers so deliveryKey is stable across retries.

Cache or persist served question IDs if you need stronger no-repeat guarantees than a single delivery scope.

Alert on sustained 429 or 503 rates before they become a customer-facing outage.