Skip to content
Zero Docs

Getting started with ZeroErrors

By the end you have sent an error report and watched it show up as an issue in the dashboard.

1. Get a key

Section titled “1. Get a key”

Reports come from running code, so you usually need a key. Sign in at dash.zeroapps.dev, open API keys in the sidebar, below the product list, and click Create. Copy the key when it is shown; it is shown once.

The same key works for ZeroErrors and ZeroVault. On your own machine you can use zero login instead. In GitHub Actions you can use the job’s OIDC token. See API keys for scope, rotation, and revoking.

Terminal window
export ZERO_API_KEY=zv_your_key_here

2. Send your first error

Section titled “2. Send your first error”

POST a report to the ingest endpoint:

Terminal window
curl -sS -X POST https://api.zeroapps.dev/errors/v1/errors \
  -H "authorization: Bearer $ZERO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"project":"docs-demo","message":"Hello from getting-started","level":"info"}'

You get back 202 and the issue it landed in:

{"issueId":"f0dc012e-0b66-4dd2-a4af-2eee08198f1f","isNew":true}

isNew is true the first time and false for later reports that group into the same issue. Send the same command a few more times and you will see the same issueId come back with isNew: false.

3. See the issue

Section titled “3. See the issue”

Open dash.zeroapps.dev/errors, filter by docs-demo, and you will see one issue titled Hello from getting-started with the count of reports you sent. Open it to see the individual events, and click Resolve when you are done.

4. Clean up the demo issue

Section titled “4. Clean up the demo issue”

Resolving only sets the status, so the demo issue stays in your list. Delete it when you no longer want it there. In the console, use the delete button on the issue row or on the issue detail page and confirm.

Over the API, list the project to get the id, then delete it:

Terminal window
curl -sS "https://api.zeroapps.dev/errors/v1/issues?project=docs-demo" \
  -H "authorization: Bearer $ZERO_API_KEY"


curl -sS -X DELETE https://api.zeroapps.dev/errors/v1/issues/$ISSUE_ID \
  -H "authorization: Bearer $ZERO_API_KEY"

The delete returns 204 with an empty body. Since docs-demo had only this one issue, the project disappears from the console too. Run the report from step 2 again and you get a brand new issue with a new id and isNew: true. See Deleting an issue.

Report fields

Section titled “Report fields”

The body of a report:

Field Required Notes
project yes 1–200 characters. Groups and labels the issue.
message yes 1–10000 characters. Its first line becomes the issue title.
stack no Up to 50000 characters. Its first at … frame helps group the issue.
level no error, warning, or info. Defaults to error.
context no Any JSON object of extra data.

Errors you may see

Section titled “Errors you may see”
  • 401 {"error":"Invalid API key"}: the key is missing or wrong.
  • 400 {"error":"Invalid error report"}: the body is malformed or missing a required field (checked only once the key is valid).
  • 429 with a Retry-After header: you are being rate-limited; wait and retry.

Next

Section titled “Next”