Idempotency & rate limits
Deduplicate retried mutations with an optional stable key, recognize cached replays and in-flight conflicts, distinguish business correlation from transport deduplication, and back off safely.
Idempotency-Key is optional on Lending Core mutations — 1 to 50 characters. When you omit it, the server generates a fresh key per attempt, so nothing correlates one attempt with the next. Send your own key on any mutation you might retry, and always on money movement.
One key per logical intent
curl -X POST "$BASE/v1/loans/7204/payments" \
-H "Authorization: Bearer $TOKEN" \
-H "LendEasy-Tenant: demo-lender" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: harbor-installment-1-maya" \
-d '{
"instrumentId": 704,
"amount": "517.14",
"currency": "USD",
"rail": "ACH",
"effectiveDate": "2026-09-12",
"source": "BORROWER"
}'If the connection drops after submission, resend the same method, path, body, tenant, and key. A completed original returns its stored result with the response header x-served-from-cache: true instead of creating another debit. If the original attempt is still executing, the duplicate returns 409 with Retry-After; wait that long and resend the same request.
Payload fingerprint on money creates
The four money-movement creates — payment create, external payment record, funding create, and external funding record — bind the key to a fingerprint of the request payload. Reusing a key with a different amount, instrument, or any other change returns 422:
{
"developerMessage": "Idempotency-Key was already used with a different payload.",
"httpStatusCode": "422",
"defaultUserMessage": "The request could not be applied.",
"userMessageGlobalisationCode": "validation.msg.idempotency.payload.mismatch",
"errors": []
}Do not “fix” the mismatch by minting a random key unless a person or deterministic workflow truly intends a second operation.
Key design
Keep keys opaque and conservative: at most 50 characters, letters, digits, and simple separators, encoding your stable workflow intent without personal or secret data:
good: pay-hbr-inst-1-2026-09-12
good: funding-hbr-disburse-v1
bad: maya-chen-ssn-4821
bad: random-key-created-on-every-retryexternalId is different
externalId correlates a durable resource to your system. Idempotency-Key deduplicates one HTTP mutation. Use both where offered:
- application external ID:
origination-HBR-2026-001; - create-request key:
create-origination-HBR-2026-001.
Changing an idempotency key does not make a duplicate externalId valid.
Unknown outcomes
| Situation | Safe behavior |
|---|---|
| Client timeout before response | Retry with identical key and body; a replay carries x-served-from-cache: true. |
409 with Retry-After |
The same request is still in flight; wait, then resend the same key and body. |
409 state conflict |
Read current state; decide whether a new intent is required. |
| Provider outcome unknown | Read the LendEasy intent; do not invoke the provider directly. |
422 fingerprint mismatch |
The key was already bound to a different payload; investigate before creating a new intent. |
422 business rule |
Correct facts/request or use declared review path; no blind retry. |
429 |
Wait at least Retry-After, then retry with same key. |
Transient 5xx / 503 |
Exponential backoff with jitter and same key. |
Bound retries by time and surface unresolved unknown outcomes to operations. Exactly-once business effect comes from idempotent intent, provider correlation, authoritative posting, and reconciliation—not HTTP retries alone.
Servicing Plane contract: mutations under /v1/servicing require an Idempotency-Key on every request — that surface keeps the mandatory-key convention.
Rate limits
Limits are tenant-, client-, and endpoint-aware. A 429 includes Retry-After and a request ID. Spread batch work, honor concurrency limits, page through lists instead of refetching them, and prefer webhooks over aggressive polling.