Skip to main content
platform

Limits & validation

active
Audience: developerUpdated 2026-10-05

Every identify and track call — whether it comes from an SDK or the Tracking REST API — is validated when Binoban ingests it. There are two outcomes when something is out of bounds:

  • The call is rejected. A structural problem (a malformed identifier, a bad event or attribute name, an oversized payload) fails the whole request. So does a call whose only identifier was a phone or email dropped by the format check. In a batch, an event without an identifier rejects the whole batch.
  • The offending attribute is dropped. A single property or trait whose value is out of range — or whose name is reserved by Binoban — is removed; the rest of the event is accepted and stored.

Knowing which is which tells you what to validate before you send.

Identifiers​

At least one identifier from the workspace's identity strategy must be present (see Identity Strategy). userId and anonymousId are optional when another identifier is sent; when present, they share one rule:

RuleValue
Max length64 characters
Allowed charactersa–z A–Z 0–9 _ - . @ :
No identifierRejected: the call must carry at least one of the workspace's identifiers

A value that is too long or contains other characters rejects the call.

Names (events, attributes, traits)​

The name (key) of an event, a custom property, and a custom trait share one rule.

RuleValue
Max length64 characters
Allowed charactersa–z A–Z 0–9 _ - .
Event nameRequired on every track call

A name that is too long or uses other characters rejects the call. (This is the name only — the 64-character limit does not apply to property values; those are covered below.)

Reserved names​

Some names belong to Binoban's own attributes. A property or trait sent under one of them is dropped from the call; everything else in the same call is processed normally, so you never lose a whole event to one reserved key.

One event name namespace is reserved: a track event must not be named with the bb_ prefix, which belongs to Binoban's own system events (bb_identify, bb_merge, the bb_notification_* family, and the rest).

On a track call, these property names are reserved:

ReservedBelongs to
Any name starting with cx_The flattened context block — context.page.url is stored as cx_pageUrl, and so on. See Track → Context for every mapping.
eventNameThe event's own name, from the event field
eventTimeThe event's timestamp, from timestamp
receiveTimeThe time Binoban received the call

On an identify call, these trait names are reserved:

ReservedBelongs toSend instead
userId · anonymousIdThe identity the call already carriesThe top-level userId / anonymousId field
smsReachable · emailReachable · pushReachable · webPushReachable · customReachableReachability, which Binoban derivessmsOptIn · emailOptIn · pushOptIn · webPushOptIn · customOptIn
Any name starting with ct_Computed traits, calculated in the workspaceDefine a computed trait

Nothing else is reserved. In particular, the plain context names (locale, appName, pageUrl, and the rest) are ordinary property names — the context block itself is stored under cx_. See Track → Reserved property names and Identify → Read-only traits.

Property & trait value types​

A property or trait value may be any of:

  • a string
  • a number
  • a boolean
  • a date — an ISO 8601 string (e.g. 2026-07-25T14:00:00Z)
  • an array of those simple types
  • an object whose fields are those types

Value limits​

These apply to each individual property or trait value. A value that breaks its limit is dropped from the event — the event itself is still accepted, now without that attribute.

Value typeLimit
String≤ 2 KB (2048 characters)
Numbergreater than −10¹⁶ and less than 10¹⁶ (bounds exclusive)
Dateafter 1900-01-01T00:00:00 and before 2299-12-31T23:59:59.999999999 (bounds exclusive)
Boolean · Array · ObjectNo per-value range check — bounded only by the 8 KB event ceiling below

Arrays and objects are accepted as-is; their elements aren't individually range-checked, so keep nested content within the overall event size limit.

System traits​

A few reserved identity traits have their own value-length limits. A value over the limit causes that trait to be dropped (the rest of the identify call still applies).

TraitMax length
firstName32
lastName32
email64
company64
jobTitle64

Payload size​

Measured on the raw request body. Exceeding the limit rejects the request with 413 Payload Too Large.

RequestMax sizeMax events
Single identify / track8 KB1
Batch800 KB100

Event timestamp​

If an event's timestamp is missing or set in the future, Binoban replaces it with the server's current time at ingestion. Send an accurate timestamp when you record historical events, or they'll all collapse to "now".

Rejection error codes​

When a call is rejected, the response body is a JSON array of { field, message } objects. The message carries the code:

CodeMeaning
error.sdk.missing.identifierThe call carries none of the workspace's identifiers
error.sdk.user.id.patternuserId has disallowed characters
error.sdk.anonymous.id.patternanonymousId has disallowed characters
error.sdk.event.name.patternEvent name has disallowed characters
error.sdk.attribute.name.lengthA property/trait name exceeds 64 characters
error.sdk.attribute.name.patternA property/trait name has disallowed characters

For authentication failures (401/404), see Authentication.