Skip to content

Errors

SDK endpoints return plain-text or JSON error responses with standard HTTP status codes.

Error response format

Most errors return a plain-text body with the error message:

Invalid or missing projectKey

HTTP status code indicates the error category. There is no structured JSON error envelope on SDK endpoints today.

Example structured format (future)

If a structured format is introduced, it may look like:

{
  "error": {
    "code": "invalid_request",
    "message": "The request payload is invalid."
  }
}

HTTP status codes

| Status | Meaning | Common causes | | :----- | :------ | :------------ | | 400 | Bad request | Missing or invalid projectKey, anonymousId, or event body | | 404 | Not found | Unknown path | | 405 | Method not allowed | Wrong HTTP method (e.g. GET on /sdk/event) | | 500 | Internal server error | Temporary server issue — retry later |

Bootstrap errors

| Message | Cause | Fix | | :------ | :---- | :— | | Invalid or missing projectKey | Project key missing or wrong format | Check ttoolabSettings.projectKey | | Invalid or missing anonymousId | Anonymous ID missing or invalid UUID | Clear storage and reload; check SDK version |

Event errors

| Message | Cause | Fix | | :------ | :---- | :— | | Invalid JSON body | Malformed JSON in POST body | Validate JSON before sending | | Invalid event payload | Required fields missing | Include projectKey, anonymousId, eventName, assignments | | Method not allowed | Non-POST request | Use POST for /sdk/event |

Client-side handling

The SDK handles errors silently to avoid breaking your site:

Failed events are queued in localStorage and retried on next load
Failed bootstrap returns null — no experiments are applied

For debugging, monitor Network tab responses during development.

Next steps