Error Codes
draftA 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 status | Code | Meaning |
|---|---|---|
401 | error.sdk.authorization.failed | The Authorization: Bearer <apiKey> header is missing, malformed, or doesn't match the source's apiKey. |
404 | error.sdk.source.notFound | sourceIdentifier 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.
403(forbidden) and429(rate limit). No code path emitting these was found for the Tracking API. Don't build retry/backoff logic around a documented429until 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 throughConfiguration.errorHandler. - Network failure. Queued events are retried; see the SDK compatibility matrix and each SDK's own reference page for retry specifics where documented.