Skip to content

docs(api): document capture API parse error messages - #21471

Closed
inkeep[bot] wants to merge 1 commit into
masterfrom
docs-writer-ai-update-2026-10-21T20-09-04-178Z-gxnmz2
Closed

inkeep[bot] wants to merge 1 commit into
masterfrom
docs-writer-ai-update-2026-10-21T20-09-04-178Z-gxnmz2

Conversation

@inkeep

@inkeep inkeep Bot commented Oct 21, 2026

Copy link
Copy Markdown
Contributor

Summary

Documents the new detailed error messages for the capture API (/i/v0/e/ and /batch/ endpoints) introduced in PostHog/posthog#120820.

Changes

Updated contents/docs/api/capture.mdx to add a "Parse errors" subsection under "Invalid events" that documents:

  • Error response structure - The JSON format returned on 400 responses with error, error_description, and error_uri fields
  • Validated fields - Lists event, uuid, distinct_id, timestamp, session_id, window_id (per event) and created_at (batch level)
  • Error message examples by issue type:
    • Wrong type: batch[0].distinct_id must be a string, got number.
    • Missing required field: batch[1].event is missing.
    • Invalid JSON: invalid JSON at line 1, column 2.
    • Truncated body: unexpected end of JSON at line 5, column 10.
  • Privacy note - Error messages never include sent values, only field names and wrong JSON types

Related


This PR was created by the Inkeep Content Writer agent, which is maintained by the Docs and Wizard team. Please reach out on Slack for help if needed.

Add a "Parse errors" subsection under "Invalid events" documenting
the new field-specific error messages for the capture v1 API from
PR PostHog/posthog#120820. Covers wrong JSON types, missing fields,
invalid JSON, and truncated body errors with example messages and
the error response structure.
@inkeep
inkeep Bot requested a review from eli-r-ph October 21, 2026 20:10
@github-actions github-actions Bot added docs Improvements or additions to product documentation, "Docs" content PR only touches files under contents/ labels Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Deploy preview

Status Details Updated (UTC)
🟢 Ready View preview Oct 21, 2026 08:25PM

Changed pages

Page Source
Capture and batch API endpoints contents/docs/api/capture.mdx

@github-actions

Copy link
Copy Markdown
Contributor

Vale prose linter → found 0 errors, 5 warnings, 0 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/api/capture.mdx — 0 errors, 5 warnings, 0 suggestions
Line Severity Message Rule
2:30 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
7:28 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
9:27 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames
510:280 warning Capitalize 'Surveys' for PostHog's product. Use 'surveys' for the general industry concept. PostHogBase.ProductNames
573:134 warning Capitalize 'Endpoints' for PostHog's product. Use 'endpoints' for the general industry concept. PostHogBase.ProductNames

@github-actions

Copy link
Copy Markdown
Contributor

Bundle report

Total JS (gzip)

10.39 MiB (no change)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint Eager size Budget Modules
✅ app 20.81 MiB (no change) report-only 2124
Largest modules in the app closure
Module Size
./src/data/mcp-tools.json 1388.5 KiB
css ./node_modules/.pnpm/css-loader@5.2.7_webpack@5.101.3/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/postcss-loader@4.3.0_postcss@8.5.6_webpack@5.101.3/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css 824.3 KiB
./src/components/Stickers/Stickers.tsx 696.4 KiB
./node_modules/.pnpm/@radix-ui+react-icons@1.3.2_react@18.3.1/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js 481.4 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs 481.2 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/trenchcoat.mjs 450.8 KiB
./node_modules/.pnpm/rehype-raw@7.0.0/node_modules/rehype-raw/lib/index.js + 29 modules 395.1 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs 385.8 KiB
./src/hooks/useCustomers.tsx + 59 modules 380.8 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/tourist.mjs 364.6 KiB
./node_modules/.pnpm/@posthog+icons@0.36.6_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/@posthog/icons/dist/posthog-icons.es.js 354.8 KiB
./node_modules/.pnpm/react-markdown@8.0.7_@types+react@16.14.66_react@18.3.1/node_modules/react-markdown/lib/react-markdown.js + 88 modules 351.4 KiB
./src/components/ProductComparisonTable/index.tsx + 127 modules 310.3 KiB
./node_modules/.pnpm/framer-motion@14.0.0_react-dom@18.3.1_react@18.3.1__react@18.3.1/node_modules/framer-motion/dist/es/render/components/motion/proxy.mjs + 127 modules 287.8 KiB
./node_modules/.pnpm/@posthog+brand@0.13.0_react@18.3.1/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs 284.1 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

@github-actions

Copy link
Copy Markdown
Contributor

Hey @eli-r-ph! This docs PR was generated for you by an agent. You're responsible for reviewing and merging it into production.

  1. Review and approve the PR
  2. Merge the PR
    a. Check the preview env and CI build and merge it yourself
    b. Enable auto-merge if you're confident in the changes

@eli-r-ph

Copy link
Copy Markdown
Contributor

Closing as superseded by #21385. These are capture v1's parse-error messages, but this page documents the legacy /i/v0/e/ and /batch/ endpoints, which answer a parse error with a plain-text failed to parse request: … instead. The capture v1 API reference in #21385 covers the v1 messages.

@eli-r-ph eli-r-ph closed this Oct 30, 2026
@github-project-automation github-project-automation Bot moved this from Backlog to Done in PostHog.com planning Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

content PR only touches files under contents/ docs Improvements or additions to product documentation, "Docs"

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

1 participant