Reliable integrations
Recover from timeouts without turning one lead into several records.
Save IDs before you send
For contacts, tasks and offers, generate a UUID in your integration and send it as id when creating the record. Save it against your source record before making the request. The existing database primary key rejects duplicate IDs, including concurrent requests.
If you lose the response:
- GET the resource using the saved UUID.
- If it exists, compare its fields with your intended record and continue.
- If it returns 404, retry creation with the same UUID.
- If creation returns 409, GET the resource again. Do not replace the UUID just to bypass the conflict.
A 409 alone does not confirm that your write succeeded. You must verify the record in your workspace. A UUID already used elsewhere can also conflict; the API does not reveal that other record.
Match retries to the operation
| Operation | Recovery after an uncertain result |
|---|---|
| GET | Retry with backoff |
| POST company | Retry with the same orgnr; it returns the existing company without changing it |
POST contact/task/offer with saved id | GET that ID; retry with the same ID if absent |
POST contact/task/offer without id | Check Aventra before retrying; you may create a duplicate |
| PATCH | Repeating the same values has the same field result, but may overwrite a teammate's newer edit |
| POST contact detail or company link | GET the details/links and inspect the result before retrying |
| POST company note | Check the company's timeline in Aventra before retrying |
There is no general Idempotency-Key support. Sending that header does not deduplicate requests. Contact details, company links and notes use integer IDs assigned by Aventra and do not accept caller-supplied IDs. Parallel requests to add identical details or links can create duplicates.
Treat the workflow as separate steps
The API does not provide transactions spanning requests. Store successful IDs and a checkpoint for each step, then resume only the missing work.
For webhook-driven integrations, acknowledge the source event after saving it durably, then process it in a worker. Deduplicate events using the source system's event ID. Do not use a person's email address as the identity of an incoming event.
Back off when asked
A 429 response includes Retry-After, in seconds. Wait at least that long before sending another request. Otherwise use bounded exponential backoff with jitter for reads and recoverable writes, for example 1, 2, 4 and 8 seconds plus a small random delay.
The API enforces 120 requests per minute per client IP (including invalid authentication attempts) and 120 requests per minute per API key. Limits apply per API instance. Integrations sharing a public IP can share the client allowance; changing IP does not reset the API-key allowance. Read Retry-After on a 429 response and keep concurrency low. A 503 temporarily_unavailable response also includes Retry-After; retry after that delay.
A 5xx response or timeout does not prove that a write failed. Follow the operation-specific recovery procedure before retrying. Fix validation, authentication and permission errors before sending the request again.
Avoid overwriting other people's work
PATCH is a partial update with last-write-wins behaviour. There are no ETags or If-Match checks in this version. Offer updates detect a concurrent status change and return 409 so the accepted/100% rule stays consistent; read the offer before retrying. Send only fields your integration owns. Do not repeatedly copy stale snapshots of a whole record back into Aventra.