# Production Guide

Use this guide when you move a PolyBridge client from a prototype to a service.

## Timeouts

Use separate client timeouts for Search and Forecast.

Forecast can take longer than Search. See `/api/rate-limits` for current timeout values.

Use `include_graph=false` when you do not need graph data. It omits `causal_graph` and reduces response size.

## Retries

Retry after the time in `Retry-After` when a request returns `429`.

Use one retry path for temporary `502` or `503` errors. Do not retry `401`, `403`, or `422` until you fix auth, access, or request body.

See `/api/rate-limits` for exact limits and retry header behavior.

## Errors

- `401`: missing auth on auth-required paths, or invalid/malformed auth on anonymous-supported paths.
- `403`: the key does not have access to that endpoint.
- `422`: invalid request shape.
- `429`: rate limit or in-flight request limit.
- `502` or `503`: temporary service or upstream error.

Forecast can return `200` with `probability: null`, an `error`, and metadata when the question is rejected or cannot produce a forecast.

Invalid or malformed auth does not fall back to anonymous mode. Remove the `Authorization` header to use anonymous mode where supported.

## Request IDs

Send `X-Request-ID` when your system already has a request ID.

Log `X-Request-ID` from responses. Also log the `request_id` field from Search and Forecast response bodies.

Include request IDs when contacting support. Do not send API keys.

## Monitoring

Track endpoint, status code, latency, `X-Request-ID`, and response `request_id`.

Track `429`, `502`, `503`, and Forecast responses with `probability: null`.

## Auth and Security

API keys provide higher-limit authenticated usage. Keep them in server-side code, scripts, or trusted agent-client environments.

Do not put API keys in browser code or query strings.

Do not log API keys.

Rotate a key if it is exposed.

Use the narrowest endpoint access that works for your client.

## Related

- Rate Limits: `/api/rate-limits`
- Standards and Conventions: `/api/standards`
- Authentication: `/api/authentication`