Reliability
How the Kontakt API behaves under load and failure, and how to build a client that recovers cleanly.
Rate limits
Each API key can make 1,000 requests per minute to https://api.usekontakt.com/v1, counted across all endpoints, including GET /ping. The count resets at the end of each one-minute window. Keys are counted separately, so two keys in the same workspace each get their own limit.
Every response carries headers that show where you stand:
| Header | Meaning |
|---|---|
RateLimit-Limit | Requests allowed per window for this key |
RateLimit-Remaining | Requests left in the current window |
RateLimit-Reset | Seconds until the window resets |
RateLimit-Policy | The limit and window length, for example 1000;w=60 |
Over the limit, the request is not processed and you get 429 with the error code RATE_LIMIT_EXCEEDED and a Retry-After header in seconds:
HTTP/1.1 429 Too Many Requests
Retry-After: 23
RateLimit-Limit: 1000
RateLimit-Remaining: 0
RateLimit-Reset: 23
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests for this API key. Retry after the time in the Retry-After header."
},
"meta": { "request_id": "..." }
}
Wait at least Retry-After seconds before you retry. For large backfills, watch RateLimit-Remaining and send requests at a steady pace from a queue rather than all at once. If you need a higher limit, email support@usekontakt.com with your expected volume.
Size limits
| Limit | Value | What happens |
|---|---|---|
| Request body | 1 MB | 413 with PAYLOAD_TOO_LARGE |
| Wallet transactions page size | 200 | Larger limit values are capped |
What a success response means
A 201 from POST /events, POST /leads, or POST /orders means the record is stored. Journeys, audience updates, computed fields, and AI follow-ups run right after the response, not before it. A journey can therefore start a moment after your call returns.
Retrying safely
| Response | Retry? |
|---|---|
| Network error or timeout | Yes, with the same idempotency key |
500 and other 5xx | Yes, with backoff |
429 | Yes, after the Retry-After header's seconds |
202 with "ignored": true | No. The source or event is switched off under Events / Sources. |
400, 401, 403, 404, 413, 422 | No. Fix the request first. |
Use exponential backoff with jitter, for example 1, 2, 4, 8, and 16 seconds, then give up and alert.
Make every retry safe to repeat:
- Send
idempotency_keyonPOST /events,POST /leads, and wallet credits and debits. A repeated key returns the original result instead of recording twice. Keys are unique across your workspace, so build them from the event type and your own record ID, such asorder.shipped:100245. POST /ordersis matched onstore_idandorder_id, so repeats update the same order.POST /customersandPOST /consentset state, so repeating them has the same result.
Request IDs
Every response has an X-Request-Id header and meta.request_id in the body. To use your own ID, send an X-Request-Id header and Kontakt echoes it back. Log it with each call. Support can trace a request quickly when you include it.
Versioning
The version is part of the path: /v1. Apart from the per-key rate limit added on October 22, 2026, changes to /v1 have added endpoints and optional fields without changing existing ones. To stay compatible:
- Ignore response fields you don't recognise.
- Don't depend on the order of keys in JSON.
- Check the API changelog for additions.
Some fields have their own conventions you should handle as documented, such as the camelCase response from POST /orders and the shorter error bodies on wallet and code endpoints. See Kontakt API.
Testing without touching live data
API keys have no test mode. Every call with any key changes the workspace it belongs to. Create a separate workspace for development and testing, and use a key from that workspace. See Workspaces.
Incidents and support
If the API returns repeated 5xx errors or times out, email support@usekontakt.com with:
- the endpoint and the time of the failures, with your time zone
- several
X-Request-Idvalues - the status codes and error bodies you received
Keep retrying with backoff while you wait. Calls that carry idempotency keys can be safely replayed once the API recovers.