Best Practices

Follow these practices to build a secure, resilient integration with the BigPanda APIs.

Secure your credentials

Use a User API Key, not an Org Token, for new integrations. User API Keys are scoped and auditable.

Store tokens in environment variables or a secret manager. Never commit a key to source control or paste it into shared code.

Give each key the minimum role permissions it needs.

Rotate keys periodically, and revoke any key that is compromised or no longer used.

Expect 429 Too Many Requests when you exceed an endpoint's rate limit. Retry after the interval indicated in the response.

Use exponential backoff for retries rather than retrying immediately.

Retry 500 Internal Server Error responses after a short wait. Do not retry 4xx responses other than 429 — fix the request first.

Wait between status checks on a Job resource rather than polling in a tight loop.

Slow your polling if you receive a 429 response. See Asynchronous operations.

Use filters and pagination instead of pulling entire datasets in one call.

Narrow incident queries with BPQL object syntax before paging.

For recurring large pulls, script paginated calls rather than one-shot requests.

Send sample calls before relying on a new or migrated endpoint in production.

Validate payloads and authentication when moving between API versions. See Versioning and deprecation.

Errors and troubleshooting: Diagnose common failures.

Pagination: Retrieve large result sets.