Skip to content

Error codes ​

Every error reply is JSON with an error field:

json
{"error": "unknown_key"}

A 429 or 503 also has a Retry-After header, in seconds.

Sending events (port 8080) ​

StatuserrorMeaningTry again?
202noneAt least one event stored. Look at rejected.n/a
400bad_requestNot valid JSON, no events, or too many events.No. Fix the request.
401unknown_keyThe key is missing, wrong, revoked, or it is a read key.No.
401stale_timestampSigned: the timestamp is missing or more than 5 minutes off.Sign again. Check the clock.
401pow_insufficientSigned: the hash has too few leading zero bits.Solve again using X-TM-Pow-Bits, retry once.
401bad_signatureSigned: wrong secret, a changed body or header, or a bad nonce (not 1 to 32 characters of A-Za-z0-9_-).No. Fix the client.
401replaySigned: this signature was already used.Sign again with a new nonce and time.
403origin_not_allowedA browser sent a website name the tenant does not list.No.
413body_too_largeThe body is over max_body_bytes.No. Send less.
415content_typeThe body is not application/json.No.
422nothing_acceptedEvery event was rejected.No. Fix the events.
429rate_limitedToo many requests from this IP.Yes, after Retry-After.
503daily cap reachedThe tenant stored its daily maximum.Yes, after the UTC day changes.
503database size cap reachedThe tenant's database reached max_db_mb.After retention frees space, or the cap is raised.
503write queue fullThe server is behind on writing.Yes, with a pause.
503tenant_unavailableThe tenant's database did not open.Yes, then check the server log.

Rejection reasons ​

These appear inside rejected, next to the event's position (i):

reasonCause
unknown_eventStrict tenant, and the name is not in the list.
invalid_event_nameOpen tenant, and the name does not match ^[a-z][a-z0-9_.]{0,47}$.
invalid_propA bad prop name, or a value that is nested, null, or text over 256 bytes. A bad prop in context rejects every event in the batch.
too_many_propsMore than 32 props.
ts_out_of_rangets is older than 7 days or more than 5 minutes ahead.

Querying (port 8081) ​

StatuserrorMeaning
400bad_requestevent is missing or malformed, agg is unknown, field is missing, or group_by or field is not a valid prop name.
400bad_rangeA time could not be read, from is not before to, or step is under 1 second.
400too_many_bucketsMore than 10,000 buckets. Use a bigger step or a shorter range.
400bad_whereA where is not in the form prop:value.
401unknown_keyThe read key is missing, wrong or revoked, or it is a write key.
413too_many_seriesMore than 50,000 rows. Narrow the range, filter, or use a bigger step.
500query_failedThe query failed or took longer than 8 seconds.
503busyFour queries are already running. Try again in 2 seconds.
503tenant_unavailableThe tenant's database did not open.

Health ​

GET /healthz returns 200 and ok on both ports. It needs no key.

Released under the MIT License.