Skip to content

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:

HeaderMeaning
RateLimit-LimitRequests allowed per window for this key
RateLimit-RemainingRequests left in the current window
RateLimit-ResetSeconds until the window resets
RateLimit-PolicyThe 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

LimitValueWhat happens
Request body1 MB413 with PAYLOAD_TOO_LARGE
Wallet transactions page size200Larger 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

ResponseRetry?
Network error or timeoutYes, with the same idempotency key
500 and other 5xxYes, with backoff
429Yes, after the Retry-After header's seconds
202 with "ignored": trueNo. The source or event is switched off under Events / Sources.
400, 401, 403, 404, 413, 422No. 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_key on POST /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 as order.shipped:100245.
  • POST /orders is matched on store_id and order_id, so repeats update the same order.
  • POST /customers and POST /consent set 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-Id values
  • 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.