PolyBridgePolyBridge APIBeta
Demo
APIProduction

Production Guide

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

Beta compatibility: API endpoints and response schemas may evolve. Clients should tolerate unknown fields, nullable values, and documented version changes.

Timeouts

Use separate client timeouts for Search and Forecast. Forecast can take longer than Search.

  • See Rate Limits for current timeout values.
  • Use include_graph=false when you do not need graph data.
  • include_graph=false 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 Rate Limits for exact limits and retry header behavior.

Errors

Handle PolyBridge status codes by cause. Forecast can also return a 200 response with no probability.

StatusMeaning
401Missing auth on auth-required paths, or invalid/malformed auth on anonymous-supported paths.
403The key does not have access to that endpoint.
422Invalid request shape.
429Rate limit or in-flight request limit.
502 or 503Temporary 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.
  • 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, and 503 responses.
  • Track 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.