Conventions

Request format

• Requests and responses are JSON in UTF-8. Send Content-Type: application/json.
• Server-side request bodies are limited to 2 MB and return 413 above that. A single browser collection request is limited to 64 KB.
• One request can carry a batch of events. Batch limits are listed on each endpoint page.

Time and time zones

• Event time is a Unix timestamp in milliseconds. Without it, the server's receive time is used.
• Events whose time is far from server time are reset to the arrival time and flagged with a warning, so a wrong client clock cannot distort reports.
• Reports split days by the project time zone, see Dates and time zones.

Dedupe

Give every server-side event a unique insert_id (an order number, for example). Duplicates from network retries are deduplicated on it and are not counted twice.

Errors

Error response shape

Failed responses include statusCode, message and code. Validation errors add issues, and rate-limit errors add retryAfter (seconds):

401 BAD_API_KEY

{
  "statusCode": 401,
  "message": "API Key 无效",
  "code": "BAD_API_KEY"
}

400 VALIDATION

{
  "statusCode": 400,
  "message": "参数校验失败",
  "code": "VALIDATION",
  "issues": ["events.0.event: Required"]
}

429 RATE_LIMIT

{
  "statusCode": 429,
  "message": "操作过于频繁，请稍后再试",
  "code": "RATE_LIMIT",
  "retryAfter": 12
}

Branch on code in your code. Do not rely on the message text, which may be in Chinese.

Common error codes

Status	Code	Meaning and fix
400	VALIDATION	The body does not match the schema. Fix the fields listed in issues and resend.
400	BAD_REQUEST	The JSON could not be parsed. Check that the body is valid JSON.
401	NO_API_KEY	No key was sent, or Authorization is empty.
401	BAD_API_KEY	The key is invalid, expired, revoked or not bound to a project.
403	SCOPE_FORBIDDEN	The key lacks the scope this endpoint needs, see Scopes.
413	PAYLOAD_TOO_LARGE	The body is over the limit. Split it into smaller batches.
429	RATE_LIMIT	Rate limit exceeded. Wait retryAfter seconds and try again.
500	INTERNAL	Server error. Retry later, and contact support if it persists.

Browser collection is the exception: it always returns 202, and dropped events are not reported as errors. See No data showing up.

Rate limits

API	Limit
Server behavior events	600 requests per minute per key, up to 1,000 events per request
Bot access records, log import	Limited by body size and lines per request, see each endpoint page
Browser collection	Limited per visitor, IP and site; excess events are dropped silently and still return 202

How many browser events a site can receive per minute depends on your plan, see Plans & quotas.

When you hit a limit

1. Do not retry a 429 immediately. Wait at least retryAfter seconds.
2. Use exponential backoff and cap the number of retries.
3. Batch where you can: one request with many events uses less quota than many single-event requests.
4. Keep the same insert_id on retries so nothing is counted twice.