Daily budget in plain language
The published model starts with a base allocation of 30,000 tokens and applies the relevant plan multiplier and number of seats. A simplified planning formula is:
Use the exact plan factors and any account-specific rules in the current Pipedrive documentation. For illustration only, if a plan factor were 2 and an account had 10 seats, the planning number would be 600,000 tokens per day. That example is arithmetic, not a promise that every account receives that exact allocation.
The important point is that seats and plan affect the budget, while endpoint complexity affects consumption. A low-volume endpoint and a broad search endpoint should not be treated as equal costs.
daily budget = 30,000 × plan factor × seat count
Distinguish burst throttling from exhaustion
A short burst can trigger a 429 even when plenty of daily budget remains. Conversely, a steady synchronization can exhaust the daily allowance without looking like a burst. Record the timestamp, endpoint, response headers, retry guidance, and a redacted body whenever a 429 occurs.
Use these signals to classify the incident:
Do not infer quota behavior from a single 429. Look at a time series.
| Signal | Likely situation | Response |
|---|
| Brief spike, then success | Burst pressure | Back off with jitter |
| Many endpoints fail for hours | Budget exhaustion or account-wide restriction | Pause and alert |
| One expensive job fails | Endpoint cost or inefficient loop | Optimize that job |
| Only one token fails | Credential or app-specific behavior | Compare credentials and scopes |
Retry without making it worse
A safe retry policy uses exponential backoff with random jitter and a maximum attempt count. Honor Retry-After if provided. Place failed work in a queue and keep the original idempotency key. Never create a new deal or person on every retry unless the operation is protected by a deterministic deduplication key.
An example policy is 1 second, 2 seconds, 4 seconds, then 8 seconds, with jitter and a hard ceiling. For a daily-budget error, do not continue this loop for hours. Mark the job deferred until the next budget window or until an operator confirms the quota state.
Find your biggest token consumers
Instrument every API call with endpoint name, method, page size, response status, duration, and an internal job ID. Aggregate by endpoint and workflow. The goal is not to guess a universal cost table; it is to discover which calls dominate your own usage under the current account and API version.
Common waste patterns include fetching the same field definitions for every record, requesting full pages when only a few records are needed, searching for the same person repeatedly, and retrieving related objects one by one. Cache metadata with a short expiry and invalidate it when an administrator changes fields.
Cursor pagination and duplicate work
Cursor pagination can make large collection reads more efficient, but it still becomes expensive if a job restarts from the beginning after each failure. Persist the last successfully processed cursor and the highest confirmed record checkpoint. On retry, reconcile the boundary page by ID rather than assuming the cursor is safe to reuse forever.
The correct recovery design depends on the endpoint’s guarantees. At minimum, writes should be idempotent and reads should tolerate a small overlap. A duplicate read is usually cheaper than a missing record.
Reduce calls in application design
Separate hot-path work from reconciliation. A webhook should enqueue an entity ID; the consumer should fetch and update the destination once. A nightly job can repair missed events without refetching every object on every run. For static field metadata, load once and share the cache among workers.
Limit concurrency per account rather than letting every worker open its own unbounded request pool. A global worker limit may still overload one small Pipedrive account if several tenants share the same process, so rate control should understand account or token identity.
A capacity example
Suppose a synchronization job reads 12,000 deals each night and makes one metadata request per deal because the field definition is not cached. That is 12,000 avoidable calls before the job even fetches the business records. Loading field metadata once per company, reusing it for the whole run, and refreshing it only when needed can remove the largest waste without changing the user-visible result.
Now split the remaining work into pages and measure the observed token consumption per page. If a page of 100 records consistently costs more than a page of 25, the larger page may not be the optimization you assumed. Capacity planning should use measurements from the endpoint and account you actually operate, then leave headroom for webhook-driven work and manual edits.
What to put on the incident dashboard
Show requests by account, status codes, estimated or reported token use, queue age, retry count, and the oldest deferred job. Add a link to the exact workflow run and redact sensitive request data. Operators need to know whether to pause one customer, one job, or all Pipedrive traffic; a single global “API error” counter cannot answer that.
The trap: “retry all 429s” is not a quota strategy. A retry is appropriate for transient pressure; it is harmful when the account has already consumed its daily budget.
Operational checklist
Before production, test a controlled throttle response, verify that Retry-After is honored, confirm that failed writes do not create duplicates, and make the dashboard show remaining-budget indicators when the platform exposes them. Alert before the budget is exhausted—for example at 70%, 85%, and 95% of your measured planning threshold.
Document who owns the token, which workflows share it, and what happens when the budget is unavailable. A clear pause-and-resume policy is better than asking a salesperson to rerun a workflow blindly.
Calculate a planning budget without false precision
Start with the allowance visible for the specific company and plan, then subtract reserved capacity for interactive requests and unexpected retries. Measure actual tokens per successful business outcome over several runs; do not assume that a request count alone predicts token use. Report both estimated remaining budget and the confidence of the estimate, because other apps or users may consume the same daily allocation.
Where these facts come from
