Skip to main content
sdk

Error Codes

draft
Audience: developerUpdated 2026-07-26

A shared, developer-facing error model across all Binoban SDKs.

Tracking API — confirmed​

The Tracking API (/api/tracker/sdk/{sourceIdentifier}/...) returns these on request-level failures:

HTTP statusCodeMeaning
401error.sdk.authorization.failedThe Authorization: Bearer <apiKey> header is missing, malformed, or doesn't match the source's apiKey.
404error.sdk.source.notFoundsourceIdentifier in the URL is missing, malformed, or doesn't resolve to a known source.
413(no error.sdk.* code — rejected before field-level validation runs)The request body exceeds the size limit: 8 KB for a single identify/track call, 800 KB for a batch (identifyBatch/trackBatch). Confirmed: thrown on every ingestion path. See Limits & validation.

Example:

POST /api/tracker/sdk/YOUR_SOURCE_IDENTIFIER/track
Authorization: Bearer wrong-key

HTTP/1.1 401 Unauthorized
[
{ "field": "", "message": "error.sdk.authorization.failed" }
]

The status codes and the error.sdk.* code strings above are read directly from the tracker source. The response envelope's exact field names are inferred from how the error is constructed server-side, not read from the shared validation-library source directly — treat them as illustrative until you've confirmed them against a live response.

Field-level validation (event/user IDs and event names over 64 characters, batches over 100 events) also returns a 4xx with the offending field — see the Tracking API reference for the limits themselves.

Pending — not yet confirmed
  • 403 (forbidden) and 429 (rate limit). No code path emitting these was found for the Tracking API. Don't build retry/backoff logic around a documented 429 until this is confirmed.
  • RTB error codes (Ad-Request / Sponsored-Ads). The RTB endpoints (/api/rtb/ad, /api/rtb/sponsoredAd) don't currently enforce Bearer authentication at all, so the 401/403 model above doesn't apply to them. Their error-response shape hasn't been documented yet.

SDK-side conditions​

These are SDK behaviors, not server error codes — the SDK degrades quietly rather than throwing:

  • Missing or blank apiKey / sourceIdentifier / apiHost. The Native SDK's configuration becomes invalid; Binoban.create(...) returns a disabled, no-op instance instead of throwing, and reports the cause through Configuration.errorHandler.
  • Network failure. Queued events are retried; see the SDK compatibility matrix and each SDK's own reference page for retry specifics where documented.
  • A refused event (4xx other than 429). The Web SDK reports the event as a failed delivery and does not retry it — the server will refuse the same payload every time. Earlier versions reported such an event as delivered; see the release notes.
  • Where a refusal's reason lives. A refused event is not stored anywhere on the server, so the code, field and reason the API returned exist only in the response the device received. The SDK keeps them while a trace session is running, and nowhere else — see Trace a visitor.

See also​