Limits & validation
activeEvery 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:
| Rule | Value |
|---|---|
| Max length | 64 characters |
| Allowed characters | a–z A–Z 0–9 _ - . @ : |
| No identifier | Rejected: 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.
| Rule | Value |
|---|---|
| Max length | 64 characters |
| Allowed characters | a–z A–Z 0–9 _ - . |
| Event name | Required 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:
| Reserved | Belongs 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. |
eventName | The event's own name, from the event field |
eventTime | The event's timestamp, from timestamp |
receiveTime | The time Binoban received the call |
On an identify call, these trait names are reserved:
| Reserved | Belongs to | Send instead |
|---|---|---|
userId · anonymousId | The identity the call already carries | The top-level userId / anonymousId field |
smsReachable · emailReachable · pushReachable · webPushReachable · customReachable | Reachability, which Binoban derives | smsOptIn · emailOptIn · pushOptIn · webPushOptIn · customOptIn |
Any name starting with ct_ | Computed traits, calculated in the workspace | Define 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 type | Limit |
|---|---|
| String | ≤ 2 KB (2048 characters) |
| Number | greater than −10¹⁶ and less than 10¹⁶ (bounds exclusive) |
| Date | after 1900-01-01T00:00:00 and before 2299-12-31T23:59:59.999999999 (bounds exclusive) |
| Boolean · Array · Object | No 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).
| Trait | Max length |
|---|---|
firstName | 32 |
lastName | 32 |
email | 64 |
company | 64 |
jobTitle | 64 |
Payload size
Measured on the raw request body. Exceeding the limit rejects the request with
413 Payload Too Large.
| Request | Max size | Max events |
|---|---|---|
Single identify / track | 8 KB | 1 |
| Batch | 800 KB | 100 |
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:
| Code | Meaning |
|---|---|
error.sdk.missing.identifier | The call carries none of the workspace's identifiers |
error.sdk.user.id.pattern | userId has disallowed characters |
error.sdk.anonymous.id.pattern | anonymousId has disallowed characters |
error.sdk.event.name.pattern | Event name has disallowed characters |
error.sdk.attribute.name.length | A property/trait name exceeds 64 characters |
error.sdk.attribute.name.pattern | A property/trait name has disallowed characters |
For authentication failures (401/404), see Authentication.