Troubleshooting

Common problems and what to do about them. If you're still stuck, the API's error message usually names the cause.

Events don't show up

Give it a few seconds. Accepted events are queued and written to storage in batches, so they can take a few seconds to appear on dashboards and in reports.
Check the response. A 201 means the events were accepted. Anything else means nothing was stored; see API errors.
Check the workspace. An API key belongs to one workspace, and events go to that workspace's signals. Make sure you're looking at the same workspace.
Check the time range. Events with an old timestamp are stored at that time, which may be outside the range a widget shows.
Using the SDK? It sends in the background and never throws. Pass an onDrop callback to see events it gave up on, and call flush() before a short-lived process exits. See SDKs.

API errors

400 Bad Request

The signal key doesn't exist or is turned off in this workspace, or a tag doesn't match the signal's tag schema. Keys are case-sensitive. In a batch, one bad event rejects the whole request.

401 Unauthorized

The API key is missing, mistyped, revoked or expired. Send it in an X-API-Key header. Check it under API Keys.

402 Payment Required

Your organization has used this month's event allowance. Sending resumes when the month turns over or the plan changes; usage is under Settings → Organization · Plan & Usage.

403 Forbidden

The key doesn't have the scope this call needs (sending events needs signals:emit), or the feature isn't included in your plan, such as OpenTelemetry ingest.

429 Too Many Requests

You're sending faster than the rate limit. Wait for the Retry-After seconds, then send the same request again. Batching more events per request (up to 500) helps.

503 Service Unavailable

Datius is catching up or briefly unavailable. Nothing was stored. Wait for Retry-After and send the same request again; the SDK and OpenTelemetry exporters do this for you.

OpenTelemetry

Nothing arrives. A metric or span is only stored when an enabled mapping rule matches its exact name. Paste a real export into the rule's Live Payload Debugger to see why it doesn't match.
Counts keep growing. Your exporter is sending cumulative totals. Set it to delta temporality; see the quickstart.
A histogram is ignored. Histograms and summaries need a fan-out rule, not a scalar one. Exponential histograms aren't supported yet.

Alerts

A rule doesn't fire. Check its condition against the signal's recent values in Live Telemetry, and that the rule is enabled and not in its cooldown.
A webhook or email didn't arrive. The Alert Rules page shows the last delivery error for each channel. Webhook and SMTP hosts must be reachable from the public internet; private addresses are refused.
Your endpoint rejects the signature. Compute the HMAC over the raw body before parsing it; see Verifying webhooks.

Dashboards and reports

A widget says the query took too long. Shorten its time range or group by a tag with fewer values, then retry.
You can't edit the dashboard. Only workspace owners and organization admins can change the layout; see Roles.

Your own storage bucket

Access denied. The credentials need list, read, write and delete on the bucket; see the permissions.
The endpoint is refused. It must be a public address, not localhost or a private network.
Events are refused with 503 and settings say Datius can't reach your storage. The bucket stopped accepting writes. Fix it or enter new credentials, then click Test connection; see If your bucket stops working.
A move of your data stopped. Settings shows why; the old location stays in use. Fix the cause and click Retry; see Switching and deleting.