Limits, errors and troubleshooting

Kentro Pixel limits, CORS behavior, reason codes, request errors, troubleshooting, background processing and retention.

This page collects the numbers and codes you need when something does not arrive: request and rate limits, CORS, per-event reason codes and request errors. It also explains what happens after ingestion and how long each kind of data is kept.

In this page

  • Limits
  • CORS
  • Per-event reason codes
  • Request errors
  • Management API errors
  • Troubleshooting
  • Processing
  • Retention

Limits

LimitValue
Browser request body (/v1/events, /v1/events/batch)64 KB
Server request body (/v1/server/events)512 KB
One event, serialized32 KB
Events per request100 on browser routes and the validate endpoint, 500 on the server route
GIF beacon e parameter16 KB of base64url
occurred_at skew7 days in the past, 5 minutes in the future
Server signature window300 seconds
Idempotency key128 characters
Rate limit, public key600 events per minute, bursts up to 1,200
Rate limit, server key6,000 events per minute, bursts up to 12,000
Rate limit, client IP on browser routes and the validate endpoint600 requests per minute, bursts up to 1,200
Rate limit, client IP on the server route1,200 requests per minute, bursts up to 2,400
Lookups of keys not seen in the last minute, per client IP60 per minute, bursts up to 120
Signup capture (SDK form)60 signups per minute per property; body up to 4 KB
Identity tokens5 distinct tokens per request, 1,024 characters each, valid at most 24 hours
Duplicate detection (event_id)At least 14 days per property
Allowed origins50 per property
Sensitive path patterns50 per property, 200 characters and 20 segments each
Custom event schemas500 per workspace are loaded
Destination event mapping50 entries
Destination replay windowAt most 180 days long, from at most 30 days back
Privacy request subject keys1 to 100

Key rate limits count events, not requests (a batch of 50 uses 50); client IP limits count requests, and lookups of unknown keys count separately, so unknown keys cannot be used to scan for valid ones. All limits are enforced per collector instance. A request refused by a rate limit on an ingestion route answers 429 RATE_LIMITED with a Retry-After header in seconds; the SDK retries it up to three times. The GIF beacon answers 200 with the code in X-Kentro-Pixel-Status, and a signup over its limit answers 202 and is not recorded.

CORS

  • The collector endpoints answer CORS themselves: Access-Control-Allow-Origin echoes the request origin when the property allows it (or *), with Vary: Origin, Timing-Allow-Origin, methods POST, GET, OPTIONS, headers Content-Type, X-Kentro-Pixel-Key and a preflight cache of 10 minutes (Access-Control-Max-Age: 600). Credentials are not used.
  • The SDK sends text/plain with the key in the body, which needs no preflight. Sending application/json or the X-Kentro-Pixel-Key header from a browser triggers a preflight, which is supported.
  • The SDK file is served with Access-Control-Allow-Origin: * and Cross-Origin-Resource-Policy: cross-origin.
  • The signup capture used by form echoes only an allowed origin and never uses credentials.
  • The management API uses the standard Kentro API CORS policy.

Per-event reason codes

CodeStatusMeaning
INVALID_ENVELOPErejectedNot an object, fails the envelope rules (types, lengths, the event_name pattern) or occurred_at is not a date.
PAYLOAD_TOO_LARGErejectedThe event is larger than 32 KB serialized.
CLOCK_SKEWrejectedoccurred_at is more than 7 days in the past or 5 minutes in the future.
SENSITIVE_PATHrejectedBrowser routes: the event's page matches one of the property's sensitive path patterns. Nothing of the event is kept, not even a rejected-event sample. See Sensitive path patterns.
TRACKING_OFFrejectedA marketing.page_viewed the SDK sent on its own (context.trigger auto or spa) while the property's matching page view setting is off. Nothing of it is kept, not even a rejected-event sample. See Page view settings.
UNKNOWN_EVENTrejectedNo builtin or custom schema for this event_name and schema_version.
RESERVED_EVENTrejectedThe name is one Kentro produces itself, refused on every route and for any schema_version. The reason says what to use instead.
SCHEMA_VIOLATIONrejectedproperties does not match the schema; reason points at the field.
SENSITIVE_PAYLOADquarantinedHealth terms, ICD-10 codes, secrets or card numbers were detected.
SENSITIVE_SCAN_INCOMPLETEquarantinedThe payload was too large or too deeply nested to scan completely.
CONSENT_DENIEDsuppressedThe effective consent for the event's purpose is denied.
GPC_OPT_OUTsuppressedGlobal Privacy Control alone denied an event with the marketing purpose.
SENSITIVE_REDACTEDacceptedAuthoritative server commerce events only: matching fields were replaced; the order still counts, but the event is never forwarded to destinations.
IDENTITY_UNVERIFIEDacceptedBrowser events: a person reference without a valid identity token was dropped; the event was recorded anonymously.

A request that passes the request-level checks answers 202 whatever the results of its events: read each event's status. An ingestion response carries the reason_code only. The reason text is answered by POST /v1/event-schemas/validate and shown with the rejected-event samples of GET /v1/ingestion/health. The two codes that keep no sample, SENSITIVE_PATH and TRACKING_OFF, count in the rejected counter of ingestion health and never appear in its last_errors.

Request errors

Request-level errors refuse the whole request. Every error body carries the code in error. The ingestion routes answer { "error": "<CODE>", "reason_code": "<CODE>", "message": "..." }. Framework errors (400 for unparsable JSON, 413, 415, 500) and the validate endpoint answer { "error": "<CODE>", "message": "..." }, and a collector that is switched off answers { "error": "COLLECTOR_DISABLED" } alone. The same codes apply to browser and server routes.

HTTPCodeWhenRetry
400INVALID_ENVELOPEThe body is not JSON, not an envelope or { "events": [...] }, or has no events.No
400BATCH_TOO_LARGEMore than 100 (browser) or 500 (server) events; the body carries max.Split the batch
401KEY_INVALIDMissing or unknown key, disabled property, or a key whose environment does not match the property.No
401KEY_REVOKEDThe key was revoked.No
401SIGNATURE_INVALIDMissing or wrong signature, or the body was not sent as application/json.After fixing the signing
401TIMESTAMP_STALEX-Kentro-Timestamp missing, not digits, or more than 300 seconds off.After re-signing
403ORIGIN_NOT_ALLOWEDThe browser origin is not in allowed_origins.No
409IDEMPOTENCY_KEY_REUSEDServer route: the idempotency key was already used with a different body.With a new key
413PAYLOAD_TOO_LARGEThe body exceeds 64 KB (browser) or 512 KB (server).Split the batch
415UNSUPPORTED_MEDIA_TYPEA content type other than application/json (or text/plain on browser routes).No
429RATE_LIMITEDToo many events for this key, or too many requests (or unknown keys) from this client.After Retry-After
500INTERNAL_ERRORUnexpected error.With backoff
503COLLECTOR_DISABLEDThe collector is switched off.Later
503INGEST_UNAVAILABLEStorage is temporarily unavailable.With backoff
503SERVICE_UNAVAILABLEThe service is briefly unavailable.With backoff
503SIGNING_UNAVAILABLEServer key secrets are temporarily unavailable.Later

Management API errors

The management API answers { "error", "message" }, plus the fields named with each route. Three answers are worth handling in every integration:

HTTPerrorWhen
403ForbiddenYour user or key lacks pixel:read or pixel:manage. message names the permission in words: You need permission to view Kentro Pixel. Ask an administrator for access. on a read, You need permission to manage Kentro Pixel. Ask an administrator for access. on a write.
409GO_STOPPEDKentro GO is stopped for the workspace. Answered by POST /v1/destinations/:id/test and POST /v1/audiences/:id/sync.
400REPLAY_RANGE_TOO_OLDPOST /v1/destinations/:id/sync with a window that starts more than 30 days back. message names the oldest day you can start on. See Replays.

Match on the status and error. The message sentences are written for people and can change.

409 GO_STOPPED

While the Kentro GO kill switch of your workspace is on, or its autonomy level is Emergency disabled, Kentro Pixel sends nothing to destinations. A test send and an audience sync are refused with 409 and a body of exactly two fields. While the kill switch is on (it is named first when both apply):

{ "error": "GO_STOPPED", "message": "The Kentro GO kill switch is on, so Kentro Pixel sends nothing to destinations until an approver turns it off." }

While the autonomy level is Emergency disabled:

{ "error": "GO_STOPPED", "message": "Kentro GO is set to Emergency disabled, so Kentro Pixel sends nothing to destinations until an approver chooses another autonomy level." }
  • Nothing was sent and nothing was queued. A retry on a timer does not help: the stop lasts until a person lifts it in Kentro GO. Send the request again after that.
  • Deliveries that are already queued are not refused. They wait and go out after the stop. See When Kentro GO is stopped.
  • A workspace where Kentro GO was never set up never gets this answer.

Troubleshooting

SymptomLikely causeWhat to do
No request leaves the pageThe script tag has no data-key, or init was called without key and endpoint; or a call was queued before init.Use the snippet from GET /v1/properties/:id/snippet, or pass both options to init, and queue init first.
Requests blocked by the browserA Content-Security-Policy without the collector host.Allow https://pixel.kentro.live in script-src and connect-src (and img-src for the GIF fallback), and allow the inline queue stub with a nonce or hash.
401 KEY_INVALIDWrong key, disabled property, or a pk_test_ key on a production property (or the reverse).Copy the key from the property; keys are tied to the property's environment.
401 KEY_REVOKEDThe key was revoked.Create a new key and update the snippet.
403 ORIGIN_NOT_ALLOWEDThe page's host is not in allowed_origins, or the request carried neither Origin nor Referer while an allowlist is set.Add the exact host or a *.domain entry (the apex needs its own entry). A Referrer-Policy: no-referrer page cannot use the GIF beacon with an allowlist.
Result rejected, SENSITIVE_PATHA browser event came from a page that matches one of the property's sensitive path patterns. A stored pattern that could not be converted matches every page except the home page.Expected for the pages you listed. Otherwise review settings.sensitivePathPatterns, and send facts about such pages from your server.
Result rejected, TRACKING_OFFA page view the SDK sent on its own arrived while settings.tracking.autoPageviews or settings.tracking.spaRoutes is false.Turn the setting on in the property's Settings tab, or stop the SDK from sending those page views with autoPageviews: false or spa: false in init.
The rejected counter of ingestion health grows, and last_errors shows nothing for itThe property's settings discard events (SENSITIVE_PATH, TRACKING_OFF): nothing of a discarded event is kept, so there is no sample.Check the property's sensitive path patterns and page view settings, or send a sample of your events to the validate endpoint with the property key.
Result rejected, UNKNOWN_EVENTThe name is not in the taxonomy, or schema_version does not match.Use a name from the taxonomy.
Result rejected, INVALID_ENVELOPEevent_name is not lower-case namespace.name, or occurred_at is not a date string: a Unix number, in seconds or milliseconds, is refused.Send occurred_at as an ISO 8601 string, for example 2026-10-09T17:00:00.000Z.
Result rejected, RESERVED_EVENTThe name is one Kentro produces itself: attribution, audience membership, conversions, Kentro GO campaign data or Kentro Email history (email.*).Stop sending it; reserved_reason in GET /v1/event-schemas names what to use instead.
Result rejected, SCHEMA_VIOLATIONA property is not on the event's allowlist, a required property is missing, or money was sent as a float.Check the reason in ingestion health or from the validate endpoint; send money as { "amount_minor", "currency" }; put identifiers under properties.customer.
Result rejected, CLOCK_SKEWoccurred_at is more than 7 days in the past or more than 5 minutes in the future.Send ISO 8601 timestamps from a synchronized clock.
Result suppressed, CONSENT_DENIED or GPC_OPT_OUTConsent is unknown or denied for the event's purpose, or GPC alone blocked a marketing event.Report consent with consentChanged; include consent in server envelopes; review settings.consent.
Result quarantined, SENSITIVE_PAYLOADA property value, the page title or a form value matched a detector, for example "appointment" or "patient" in a page title.Keep medical terms, secrets and card numbers out of event data and page titles.
Result duplicateThe event_id was already accepted for the property, or an envelope without event_id was identical to an earlier one.Give every real-world event its own event_id; expect duplicate on retries.
429 RATE_LIMITEDMore events than the key's budget, or more requests (or unknown keys) from one client IP than its budget; message says which.Wait for Retry-After. Batching lowers the number of requests, not the number of events; use a server key for high-volume backend traffic.
401 SIGNATURE_INVALID on the server routeThe signed string differs from the bytes sent, the secret belongs to another key id, the sha256= prefix or lower-case hex is missing, the secret was base64-decoded, or the body was not sent as application/json.Sign the exact string you send, with the secret as given, and send Content-Type: application/json.
401 TIMESTAMP_STALEThe clock is off by more than 300 seconds, or the timestamp is in milliseconds.Send Unix seconds from a synchronized clock.
Result accepted with IDENTITY_UNVERIFIEDA person reference without a valid identity token (missing, malformed, expired, or signed by a revoked key or a key of another property).Mint tokens as in Identity tokens; never put subject_ref in browser events.
409 IDEMPOTENCY_KEY_REUSEDThe idempotency key was already used with a different body.Use a new key for every new batch.
503 COLLECTOR_DISABLED, INGEST_UNAVAILABLE, SIGNING_UNAVAILABLEThe collector is switched off, or storage or secrets are temporarily unavailable.Retry later with the same event_id values.
Signups from the form command never arriveThe property's allowed_origins is empty or misses the page's host (403), the consent checkbox was not checked, the email field was not found, or a Content-Security-Policy blocks https://t.kentro.email.Add the host to allowed_origins, check consentSelector and emailField, and allow the host in connect-src. Set debug: true to see option warnings.
Events in the debugger but not in analytics or a destinationProcessing runs in the background; a destination sends only mapped events once it is enabled, and only with the consent it needs.Check processing_status in the debugger, the destination's status and mapping, and its delivery history (suppressedReason).
Deliveries stay queued; a test send or an audience sync answers 409 GO_STOPPEDKentro GO is stopped for the workspace: the kill switch is on, or the autonomy level is Emergency disabled.The deliveries go out once an approver lifts the stop in Kentro GO, within each provider's limits (Meta takes events up to 7 days old). Send the test or the sync again after that.
404 Not Found on every management routeThe management API is switched off on this environment.During the preview it is enabled per environment; contact [email protected] for access.

Processing

After ingestion, Kentro's background processor works through accepted events in the order they arrived:

  • People and sessions. Each event is attached to the person keys it carries. A server event that carries both the visitor's anonymous_id and a subject_ref or commerce_subject_ref links that anonymous visitor to the person; browser events never create a link, not even with a verified identity token. Sessions follow settings.session (30 idle minutes by default) and record the touchpoint: UTM values, hashed ad click ids, the campaign reference and the referrer class. Sessions, touchpoints and browser conversions need analytics or marketing consent.
  • Kentro Email touchpoints. A click on a tracked Kentro Email link records a touchpoint of channel email (source kentro_email, medium email) for that contact, so attribution can credit email. Opens are not touchpoints.
  • Consent record. Explicit consent choices are filed as described in Consent and privacy.
  • Conversions. commerce.order_placed and commerce.order_paid record an order, and cancellations and refunds correct it; marketing.lead_captured, marketing.signup_completed and marketing.demo_booked are lead conversions. Each order counts once (a server copy wins over a browser copy, commerce.order_paid over commerce.order_placed) and each lead once per conversion type and lead_ref.
  • Destinations. Each mapped event of an enabled destination becomes a delivery, sent with up to 8 attempts. The person's consent record is checked when the delivery is created, and for Meta and Google Ads again when it is sent. While Kentro GO is stopped nothing is sent: deliveries wait (see Destinations).
  • Attribution. Last-touch attribution over 30 days is refreshed automatically when conversions change; the other models run on request (POST /v1/analytics/attribution/runs).
  • Audiences. Active audiences are recomputed about every 10 minutes, and again at the start of a sync. A sync sends who joined and who left since the previous sync to that destination, and the full membership when the destination's 30-day delivery history holds no earlier sync that was sent, accepted or is still waiting (see Audience membership).
  • Privacy requests run as described in Consent and privacy.

Retention

Retention is enforced automatically. Changing settings.retention applies to the history already stored: a longer period keeps existing history longer, and a shorter one removes stored history past the new period, starting with the next daily retention run.

DataKept
Event historyAt least 13 months, or longer when settings.retention.journalMonths asks for it
Events that could not be processedKept in the processing queue with the error, as a copy of the event without raw click ids, the raw page URL and the user agent, until a delete or anonymize privacy request for the person removes or rewrites them. A copy that reached the event history expires like every other event.
Ingestion receipts and server batch idempotency keysAs long as the property's event history
Accepted event ids, for duplicate detection14 days
Rejected-event samples (ingestion health)settings.retention.errorsDays: 30 days by default, 1 to 365
Attribution resultsThe automatic last-touch results (30-day window): the two newest runs. Runs you request: until both the end of their period and the time the run started are older than the longest event history among the workspace's properties.
Order reconciliation recordsAs long as the property's event history, counted from their last update
People records (person keys and the links between them)Removed once a person has not been seen for the full event retention period, is a current member of no audience and has no conversion within that period. An audience that is archived or back in draft keeps its members, and so keeps them from removal, until it is deleted. Kentro Email contacts, and people a Kentro Email contact's customer record points to through an authorized CRM link, are kept. Deletion records of privacy requests are kept, so a deleted person is never recreated.
Consent recordsAs long as the person's record, and at least for the event retention period. Retention never removes a consent withdrawal record. A delete or anonymize privacy request removes the person's consent records, withdrawals included.
Audience membership historyCurrent memberships while they last; a leave is kept 90 days
Raw ad click ids90 days, then removed from sessions and events
The full browser user agent of marketing-consented events30 days
The salted hash of the client IP address on ingestion receipts (the raw address is never stored; the salt changes every UTC day)30 days on the receipt every request leaves, then cleared while the receipt and its counts stay. The idempotency record of a server batch sent with X-Kentro-Idempotency-Key keeps no hash.
Delivery history30 days; a delivery still waiting to be sent is kept until it is sent or gives up, which includes the whole time Kentro GO is stopped
Records of queued replays, audience syncs and attribution runs7 days after the job completes (a refused job completes too); a job that failed after its retries is kept
Privacy request records24 months after completion, then deleted
Privacy export downloads24 hours