Reference
Errors, limits and paging
One error envelope everywhere. Every response, success or failure, carries X-Request-Id; quote it when you write to us.
Fixed across packs
{
"error": "a sentence for a person",
"code": "for_your_code_to_branch_on"
}Error codes
StatusCodeMeaningWhat to do
400bad_requestMalformed JSON, an unknown event type, a broken scope rule, an attribute the pack's schema refuses, or one thing asked for two ways: q alongside external_ref, subject_id alongside subject_ref.Read error; the sentence names the field. Do not retry as-is.
400validation_errorA fixed field is missing or the wrong shape.Fix the request; do not retry as-is.
401unauthorizedNo bearer key.Send Authorization: Bearer utl_live_…
401invalid_api_keyKey not recognised.Check for truncation; the checksum catches typos.
401api_key_revokedKey was revoked in Account.Create a new key.
401api_key_expiredKey passed its expiry.Roll the key.
403insufficient_scopeKey lacks the scope the route needs.Create a key with the scope named.
403wrong_productKey belongs to another product.Use a Raven key on Raven paths.
403org_suspendedOrganisation is suspended. Reads still work; writes are refused.Settle the account in Utilitay Account.
403subscription_suspendedThis instance's subscription is suspended. Reads still work.Pay the open invoice in Utilitay Account.
404not_foundNo such record in this instance — or the key does not reach the instance. A key cannot be used to find instances.Check the id, the instance slug and the key's reach.
405method_not_allowedThe path exists; the method does not. There is no DELETE.Use deactivate or void.
409conflictThe record already exists, e.g. a phone number already on file.Read the existing record; do not retry.
413too_largeBody over 1 MB.Send less.
429rate_limitedOver 10/s per key or 30/s per instance.Wait Retry-After seconds, then retry.
502upstream_errorThe gateway could not get an answer from Raven.Retry with backoff, with the same Idempotency-Key.
503unavailableBriefly down.Retry with backoff.
Rate limits
10 requests/s per key. 30 requests/s per instance. Over the limit you get 429 with Retry-After. There are no X-RateLimit-* headers. Bodies over 1 MB are refused with 413.
Pagination
?limit (default 50, max 200), ?offset, ?q. List responses are bare JSON arrays: no envelope, no cursor, no total. Stop when a page comes back shorter than limit.
Idempotency
Idempotency-Key header or event_ref in the body, on POST /events only. Events also dedupe on the type’s dedupe_fields, and POST /links upserts on the pair.