Errors

Tiny returns straightforward JSON errors and, for public ingest failures, often includes an attemptId that lets you line the failure up with the debug view.

How errors are returned

Workspace APIs typically return a compact error shape:

{
  "error": "organizationId is required"
}

Validation-heavy ingest failures return more detail:

{
  "error": "invalid_events_payload",
  "message": "Events payload is invalid",
  "issues": [
    {
      "code": "missing_session_id",
      "field": "sessionId",
      "message": "sessionId is required"
    }
  ],
  "attemptId": "attempt_123"
}

Status codes

  • Name
    400
    Description

    Missing required request fields such as organizationId or publicKey, or malformed request shapes outside the tracked validation flow.

  • Name
    401
    Description

    Missing or invalid bearer token. Tiny uses unauthorized for these cases.

  • Name
    402
    Description

    Billing entitlement issue, such as seat_limit_reached when inviting a new member beyond the plan limit.

  • Name
    403
    Description

    Permission or source-protection failure. Examples include Forbidden, tracking_source_origin_not_allowed, tracking_source_inactive, and invalid_session_for_source.

  • Name
    404
    Description

    Requested entity was not found, such as user_not_found.

  • Name
    409
    Description

    Conflict such as already_member.

  • Name
    413
    Description

    Public ingest payload exceeded the source's payload-byte limit.

  • Name
    422
    Description

    Bootstrap or events payload failed structured validation. Tiny returns an issues array explaining what was wrong.

  • Name
    429
    Description

    Public ingest request-rate limits were exceeded.

  • Name
    500
    Description

    Unexpected server error.

  • Name
    503
    Description

    Service is unavailable or not configured. Billing actions use this when Stripe is not configured for the environment.

Common error codes

  • Name
    organizationId is required
    Description

    Common across workspace-scoped APIs when the request does not specify the active workspace.

  • Name
    unauthorized
    Description

    The bearer token is missing, expired, or invalid.

  • Name
    user_not_found
    Description

    The invite target does not exist in the auth system.

  • Name
    already_member
    Description

    The user is already an active member of the workspace.

  • Name
    seat_limit_reached
    Description

    The workspace exceeded the current plan's member limit.

  • Name
    tracking_source_origin_not_allowed
    Description

    The request origin is not listed in the source's allowed origins.

  • Name
    tracking_source_inactive
    Description

    The source exists but is inactive.

  • Name
    invalid_session_for_source
    Description

    The supplied session belongs to a different source or no longer matches the source being used.

  • Name
    invalid_bootstrap_payload
    Description

    Bootstrap validation failed. Check issues for fields such as ingestVersion, sdkVersion, anonymousId, or page.

  • Name
    invalid_events_payload
    Description

    Event-batch validation failed. Check issues for fields such as batchId, sentAt, sessionId, event IDs, event types, or page payloads.

  • Name
    payload_too_large
    Description

    The request body exceeded the source's payload-byte limit.

  • Name
    rate_limit_exceeded
    Description

    The source exceeded its per-minute ingest rate limit.

Debugging with attempt ids

Public ingest failures often include attemptId. Use it with Analytics > Setup > Debug to find:

  • the exact raw payload Tiny received
  • the normalized payload Tiny derived
  • the source and origin verdict
  • per-event outcomes for accepted, duplicate, and rejected events

When the failure is install-related, this is usually faster than debugging only from browser logs.

Was this page helpful?