Idempotency

Networks fail. If a request times out, you can’t tell whether it reached us. Idempotency keys let you retry a POST request safely: if we’ve already processed a request with the same key, we return the original result instead of doing the work again.

This matters most for actions with consequences outside Trimline, such as approving a draft, which sends an email to a vendor.

Sending a key

Add an Idempotency-Key header to any POST request. Use a value that’s unique to the operation, such as a UUID v4, or a string built from your own record IDs.

curl -X POST https://api.trimline.tech/v1/drafts/drf_3Nc81Ab/approve \
  -H "Authorization: Bearer $TRIMLINE_API_KEY" \
  -H "Idempotency-Key: 0f8d3c56-9a1e-4e4b-8d1a-55e0a6f1c2b7"

How it behaves

• The first request with a given key is processed normally, and we save its status code and response body.
• Later requests with the same key and the same parameters return the saved response, including errors, with an Idempotent-Replayed: true header.
• If the same key arrives while the first request is still running, the second gets a 409 with the code idempotency_request_in_progress. Retry it after a short wait.
• Reusing a key with different parameters returns a 400 with idempotency_key_reused.
• Keys expire after 24 hours.

Which requests need it

GET and DELETE requests are idempotent by definition, so they ignore the header. PATCH requests accept it but rarely need it. We strongly recommend it for every POST, and it’s required for these endpoints:

• POST/v1/drafts/:id/approve
• POST/v1/negotiations/:id/offers/:offer_id/accept
• POST/v1/contracts/:id/send_notice