Evidence-Driven Flexport Quota Control

Overview

Build controls from documented endpoint constraints and observed responses, not a fictional universal requests-per-minute number. The clearest fixed budget is OAuth token issuance: at most 10 token requests per day per documented credential flow.

Prerequisites

Inventory by OAuth, REST endpoint, and MCP tool
Shared token cache and per-workload queues
Observed statuses, provider messages, and latency without sensitive payloads

Instructions

Step 1: Separate budgets

Track token acquisition, read traffic, mutations, webhook processing, and MCP tool calls independently.

Step 2: Eliminate token churn

Reuse each 24-hour OAuth JWT through a shared cache and single-flight refresh so business concurrency does not consume the 10/day token-request budget.

Step 3: Honor explicit evidence

Apply endpoint-specific documented limits and provider retry signals when present. Do not assume rate-limit headers or Retry-After exist universally.

Step 4: Shape reads

Use documented page sizes/cursors or links, avoid expensive expansions on index calls, and stop pagination when the business window is satisfied.

Step 5: Serialize mutations

Queue bookings and record creation by business key, cap attempts, and reconcile ambiguous outcomes before retry.

Step 6: Tune from receipts

Change concurrency only from measured latency/error evidence and preserve the before/after decision.

Authentication

REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions.

Tool Discipline

Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change.

Output

Scoped decision or implementation artifact
Redacted operation and validation receipt
Failure, rollback, and follow-up ownership record

Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it:

surface: rest-v3
operation: shipment-read
decision: approved
outcome: verified
evidence:
  release_sha: recorded-out-of-band
  provider_reference: redacted
rollback_owner: logistics-platform

Examples

An importer reads freight invoices from /invoices in pages of 10 as recommended for performance, caches its OAuth token, limits concurrent reads based on observed behavior, and never claims a global Flexport quota that the docs do not publish.

Error Handling

Failure	Response
429 without retry metadata	Pause the affected surface, use bounded backoff with jitter, and seek provider guidance.
Token requests approach 10/day	Stop acquisition and repair cache sharing before tokens expire.
Queue grows after concurrency increase	Roll back the increase and inspect endpoint latency/error evidence.
Mutation throttled	Reconcile existing business references before resubmitting.

flexport-rate-limits