Errors and limits

Every status code the Read API returns is below, with what causes it and what you do about it.

Error shape

Every error is JSON with an error string:

{ "error": "start_date and end_date required (ISO 8601)" }

/ads adds a stable code. /commerce-metrics and the cost-import routes add a stable reason. Branch on code or reason rather than the error text, which we reword.

{ "error": "Ads analytics query failed or timed out", "code": "ads_provider_read_failed" }

Status codes

Status	`error`	Cause	Fix
`400`	`start_date and end_date required (ISO 8601)`	One date is missing, or `Date` cannot parse it.	Send both as ISO 8601, such as `2026-07-01T00:00:00Z`.
`400`	`type must be browser, os, or deviceType`	`/devices` got another `type`.	Use `browser`, `os`, or `deviceType`.
`400`	`use date_from/date_through or start_date/end_date, not both`	`/ads` got both date forms.	Send one form.
`400`	`Ads date ranges must contain 1-366 days`	The `/ads` range is empty or longer than 366 days.	Split the range into 366-day pages.
`400`	`platform must be meta, google, or tiktok`	`/ads` got another `platform`.	Use `meta`, `google`, or `tiktok`.
`400`	`cursor is invalid or belongs to another sort`	The `/ads` `cursor` came from a request with a different `sort`.	Restart the page walk. Keep `sort` identical across pages.
`400`	`start_date and end_date must be UTC hour instants with start < end`	`/commerce-metrics` got instants that are not on the hour, or out of order.	Round both to an exact UTC hour. Put `start_date` first.
`400`	`requested interval cannot exceed 366 days`	The `/commerce-metrics` interval is too long.	Request 366 days or fewer.
`400`	`end_date cannot be in the future`	`/commerce-metrics` got a future `end_date`.	Use the current hour or earlier.
`400`	`Query parameter … is not allowed`	A request tried to override the commerce policy through the query string.	Remove the parameter. The policy is server-held.
`401`	`Invalid or missing Agent API key. Use: Authorization: Bearer dk_agent_xxxxx`	No key, wrong scheme, a `dk_` write key, or an unknown key.	Send the Agent key. See Authentication.
`403`	`A workspace agent API key plus operator authorization is required for cost imports`	You called a cost-import route.	Do not call it. Datalyr operates these two routes.
`404`	`Not found`	The path is not one of the sixteen Read API endpoints.	Compare the path with the endpoint table.
`404`	`User not found`	`/users/{userId}` matched no summary row and no journey row.	Take an ID from `/users`. Widen the date range on `/users`.
`404`	`Ad account not found in this workspace`	The `/ads` `account_id` belongs to another workspace.	Drop `account_id`, or use an account the workspace owns.
`405`	`Method not allowed`	You sent anything other than `GET` to a `/v1` endpoint.	Use `GET`.
`429`	`Rate limit exceeded`	The workspace passed 100 requests in 60 seconds, or the rate-limit store was unreachable.	Wait for `Retry-After`, which is `60`. Then retry.
`500`	`Internal server error`	A handler threw, or a Tinybird query passed its 10-second timeout.	Retry once. If it repeats, narrow the date range and contact support.
`503`	`Ads analytics query failed or timed out`	Code `ads_provider_read_failed`. The ad-metrics store did not answer.	Retry with backoff. Ad data is unchanged.
`503`	`Ads analytics storage is not configured`	Code `ads_storage_unavailable`.	Contact support. No client-side fix exists.
`503`	Commerce payload with a `reason` field	`/commerce-metrics` could not certify the answer.	Read `reason`. `commerce_policy_does_not_cover_interval` means the policy starts after your `start_date`.

Never treat 503 from /ads or /commerce-metrics as zero spend or zero revenue. These endpoints fail loudly on purpose, so that a read you could not complete never lands in a report as a real number.

Rate limit

Limit	Value
Scope	One workspace, across every `/v1` endpoint
Window	60 seconds, sliding
Requests per window	100
Response over the limit	`429` with `Retry-After: 60`
Behavior when the limit store is unreachable	Fail closed, so every request returns `429`

The limit counts requests, not rows. One /events request for 1000 rows costs the same as one /workspace request.

Parameter limits

Endpoint	Parameter	Minimum	Maximum	Default
`/events`	`limit`	1	1000	100
`/events`	`offset`	0	No maximum	0
`/events`	`event_name`	No minimum	50 comma-separated names, 200 characters each	No default
`/users`	`limit`	1	1000	100
`/traffic`	`limit`	1	100	20
`/tags`	`limit`	1	100	20
`/devices`, `/locations`	`limit`	1	100	15
`/realtime`	`time_window` minutes	1	60	30
`/realtime`	`visitors` returned	No minimum	50	No default
`/attribution`	`window_days`	1	365	30
`/attribution`	campaign rows returned	No minimum	100	No default
`/ads`	`limit`	1	200	50
`/ads`	`cursor` characters	No minimum	500	No default
`/ads`	`q` characters	No minimum	200	No default
`/ads`, `/commerce-metrics`	Range days	1	366	No default

We clamp a value above the maximum instead of returning 400, so an oversized limit still gives you a page of data.

Ingest limits

Event ingest runs on a different host, https://ingest.datalyr.com, and has its own limits.

Limit	Value	Response over the limit
Events per workspace per minute	10,000	`429` with `Retry-After: 60`
Request body on `/`	1 MB	`413` `Payload too large`
Request body on `/track`	256,000 bytes	`413` `Payload too large`
`Content-Type`	Must match `application/json`	`415`
SKAdNetwork report body	16 KB	`413`

The ingest rate limit counts events, not requests. A batch of 50 events costs 50.

Verify a limit

Send 101 /v1/workspace requests inside one minute. Request 101 returns 429 and the header Retry-After: 60.

Read API: the endpoint list and date rules.
Authentication: key types and the 401 body.
Web SDK: how the browser SDK retries a 429.

API Reference

Analytics

Events and users

Attribution and revenue

Workspace

Error shape

Status codes

Rate limit

Parameter limits

Ingest limits

Verify a limit

Next

​Error shape

​Status codes

​Rate limit

​Parameter limits

​Ingest limits

​Verify a limit

​Next

Error shape

Status codes

Rate limit

Parameter limits

Ingest limits

Verify a limit

Next