Rate Limits & Idempotency

API v1 is being deprecated. Use v2 for new integrations. For existing integrations, see the migration guide and API Reference v1.

Manage v2 requests and retries with rate limits, idempotency, and concurrency headers. For existing integrations, see V1 limits and retries.

Limits

ScopeLimit
Organization, shared across its API traffic100 requests per minute
Credential20 requests per 10 seconds

All keys share the organization budget. V2 also limits each API key, or each OAuth client/user pair. Either limit can return 429.

Rate-limit headers

HeaderMeaning
RateLimit-LimitLimit reported by the limiter
RateLimit-RemainingRequests remaining in its window
RateLimit-ResetSeconds until its window resets
Retry-AfterSeconds to wait after a 429

V2 has two limits, so the rate-limit headers are not a complete view of both budgets. On 429, honor Retry-After, then retry with a little jitter.

Rate-limit response

An organization-limit response looks like this:

{
  "code": "RATE_LIMITED",
  "message": "Rate limit exceeded. Please try again later.",
  "requestId": "example-request-id",
  "details": { "retryAfter": 60, "limit": 100 }
}

For the credential limit, Retry-After and details.retryAfter are 10, and details.limit is 20. Prefer the response's retry timing over a hard-coded delay.

Use webhooks, cache reusable reads, and avoid tight polling loops.

Idempotency

Where the v2 reference marks Idempotency-Key as required:

  1. Generate a key for one intended operation, up to 255 characters.
  2. Save it with the request payload before sending.
  3. If the response is lost, retry with the same credential, operation, key, and payload. A completed request replays its stored status and body.
  4. Use a new key for a new intended operation, not as a way to bypass an uncertain result.

Keys are scoped to organization, caller, and operation. Replay protection lasts seven days; do not rely on it afterward.

V2 error codeMeaningNext step
IDEMPOTENCY_KEY_REQUIREDThe operation requires a keySupply one before submitting
IDEMPOTENCY_KEY_CONFLICTThe key was used with different inputRestore the original input for a retry; use a new key only for a separate operation
IDEMPOTENCY_REQUEST_IN_PROGRESSThe prior request has no completed response yetWait and retry with the same key; reconcile resource state if it remains unresolved
APPLICATION_SUBMISSION_OUTCOME_UNKNOWNA lender submission cannot yet be confirmedRead the project's financing state; do not submit again under a new key

For financial submissions, follow the operation's specific recovery instructions. A timeout or 5xx does not prove that an external side effect did not happen.

Concurrent updates in v2

Idempotency prevents duplicate operations; If-Match prevents stale updates.

Where If-Match is required, read the target resource and send its exact ETag, including quotes, with your write:

If-Match: "ETAG_FROM_THE_LATEST_READ"
  • 428 / IF_MATCH_REQUIRED: read the resource and supply its ETag.
  • 412 / ETAG_MISMATCH: another change occurred. Read again, reconcile your intended change, and retry with the new ETag.

Use the changed resource’s ETag: a project’s cannot replace an equipment or subscription ETag. Required headers vary by operation.

V1 limits and retries

V1 and v2 share the 100-request/minute organization budget. The additional v2 credential limit does not apply to v1.

GET /external/v1/projects/{project_id} also has a limit of 20 reads per minute per organization, shared across project IDs and API keys. This stacks with the 100-request organization limit. Its 429 response reports limit: 20 and retryAfter: 60. Prefer webhooks to polling full project details.

Rate-limit response

{
  "err": "Rate limit exceeded. Please try again later.",
  "retryAfter": 60,
  "limit": 100
}

Retrying writes

Do not assume v1 writes support v2's Idempotency-Key behavior. Follow the specific operation's contract. Reads are safe to retry. After a write timeout or unknown outcome, check the resource before repeating the write, for example using your externalProjectId. A client-side reference is not a general exactly-once guarantee.