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
| Scope | Limit |
|---|---|
| Organization, shared across its API traffic | 100 requests per minute |
| Credential | 20 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
| Header | Meaning |
|---|---|
RateLimit-Limit | Limit reported by the limiter |
RateLimit-Remaining | Requests remaining in its window |
RateLimit-Reset | Seconds until its window resets |
Retry-After | Seconds 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:
- Generate a key for one intended operation, up to 255 characters.
- Save it with the request payload before sending.
- If the response is lost, retry with the same credential, operation, key, and payload. A completed request replays its stored status and body.
- 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 code | Meaning | Next step |
|---|---|---|
IDEMPOTENCY_KEY_REQUIRED | The operation requires a key | Supply one before submitting |
IDEMPOTENCY_KEY_CONFLICT | The key was used with different input | Restore the original input for a retry; use a new key only for a separate operation |
IDEMPOTENCY_REQUEST_IN_PROGRESS | The prior request has no completed response yet | Wait and retry with the same key; reconcile resource state if it remains unresolved |
APPLICATION_SUBMISSION_OUTCOME_UNKNOWN | A lender submission cannot yet be confirmed | Read 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.

