docs(config): clarify maxRetries scope

[dustinbyrne]

💡 Motivation and Context

Stacked on #740; companion clarification: PostHog/posthog-ios#819.

Clarify that core PostHogConfig.maxRetries controls push-subscription registration retries, with a default of 3. It does not limit event, replay, or log ingestion retries. Retryable ingestion failures retain queued records for later flush triggers, subject to backoff; capacity is controlled by maxQueueSize for events/replay and logs.maxBufferSize for logs.

The stack base already implements this behavior and includes its release notes. This PR clarifies the API documentation.

💚 How did you test it?

• make testJava — all 958 core tests in 53 classes passed.
• make checkFormat and ./gradlew :posthog:apiCheck — passed.
• Java getter/setter consumer compiled with -Xlint:deprecation -Werror; JVM public signatures match the stack base exactly.
• Checked that the net stack diff contains only API documentation.

Checks used JDK 17. Android-specific tests and the compliance-adapter build were not run.

📝 Checklist

• Reviewed the submitted code.
• Updated API documentation.
• Validated public API compatibility and existing runtime behavior.

🤖 Agent context

Autonomy: Human-driven (agent-assisted).

Implemented with Pi and reviewed by a fresh read-only Pi reviewer. Tooling: Git, GitHub CLI, Make, Gradle, and Java compiler checks.

[greptile-apps]

_{Reviews (1): Last reviewed commit: "chore(config): deprecate maxRetries" | Re-trigger Greptile}

[github-actions]

⚠️ `posthog` is modified but this PR has no changeset

This is informational — the PR is not blocked. Click the triangle above to collapse, or push a fix and this comment will auto-delete.

Modified in this PR but no changeset added:

• posthog

If this change should ship, run pnpm changeset and select a bump level.
If it isn't user-facing (refactor with no behavior change, internal tooling, generated files), no action needed.

[github-actions]

posthog-android Compliance Report

Date: 2026-09-10 22:42:43 UTC
Duration: 117806ms

✅ All Tests Passed!

46/46 tests passed

---

Capture Tests

✅ 29/29 tests passed

View Details

Test	Status	Duration
Format Validation.Event Has Required Fields	✅	284ms
Format Validation.Event Has Uuid	✅	19ms
Format Validation.Event Has Lib Properties	✅	16ms
Format Validation.Distinct Id Is String	✅	16ms
Format Validation.Token Is Present	✅	18ms
Format Validation.Custom Properties Preserved	✅	17ms
Format Validation.Event Has Timestamp	✅	15ms
Retry Behavior.Retries On 503	✅	7022ms
Retry Behavior.Does Not Retry On 400	✅	4018ms
Retry Behavior.Does Not Retry On 401	✅	4023ms
Retry Behavior.Respects Retry After Header	✅	7022ms
Retry Behavior.Implements Backoff	✅	17028ms
Retry Behavior.Retries On 500	✅	7017ms
Retry Behavior.Retries On 502	✅	7018ms
Retry Behavior.Retries On 504	✅	7015ms
Retry Behavior.Max Retries Respected	✅	17018ms
Deduplication.Generates Unique Uuids	✅	28ms
Deduplication.Preserves Uuid On Retry	✅	7014ms
Deduplication.Preserves Uuid And Timestamp On Retry	✅	12019ms
Deduplication.Preserves Uuid And Timestamp On Batch Retry	✅	7014ms
Deduplication.No Duplicate Events In Batch	✅	23ms
Deduplication.Different Events Have Different Uuids	✅	14ms
Compression.Sends Gzip When Enabled	✅	12ms
Batch Format.Uses Proper Batch Structure	✅	11ms
Batch Format.Flush With No Events Sends Nothing	✅	8ms
Batch Format.Multiple Events Batched Together	✅	23ms
Error Handling.Does Not Retry On 403	✅	4014ms
Error Handling.Does Not Retry On 413	✅	4015ms
Error Handling.Retries On 408	✅	5018ms

Feature_Flags Tests

✅ 17/17 tests passed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	✅	24ms
Request Payload.Flags Request Uses V2 Query Param	✅	14ms
Request Payload.Flags Request Hits Flags Path Not Decide	✅	33ms
Request Payload.Flags Request Omits Authorization Header	✅	19ms
Request Payload.Token In Flags Body Matches Init	✅	16ms
Request Payload.Groups Round Trip	✅	14ms
Request Payload.Groups Default To Empty Object	✅	16ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	✅	14ms
Request Payload.Disable Geoip Omitted Defaults To False	✅	12ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	✅	10ms
Request Lifecycle.No Flags Request On Init Alone	✅	6ms
Request Lifecycle.No Flags Request On Normal Capture	✅	13ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	✅	24ms
Request Lifecycle.Mock Response Value Is Returned To Caller	✅	15ms
Retry Behavior.Retries Flags On 502	✅	315ms
Retry Behavior.Retries Flags On 504	✅	318ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	✅	16ms