Errors

API errors return JSON with a stable code, a plain message, and a doc_url that links to the matching section below:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "code": "unregistered_sender",
  "message": "Unregistered sender. Send a valid project key in the X-Api-Key header, or set this site's domain on a web property.",
  "doc_url": "https://analytics.specvista.com/docs/errors#unregistered_sender"
}

Match on code, never on message, which may change. Some older responses, such as validation from the account page, have no code. Each doc_url opens this page; agents can read the same section as Markdown at https://analytics.specvista.com/docs/errors.md.

Sending events

unregistered_sender

401 from /ingest, /ingest/identify, /ingest/batch and /sdk/linked-domains. No property matches the X-Api-Key header, or, without a key, the X-Domain header or domain field. Copy the key again from the Properties page or GET /projects. The key may have been rotated. For keyless browser tracking, set the property's domain to the site's hostname without www..

invalid_api_key

401 from /forget. The X-Api-Key header is missing or matches no property. Send a backend property's key.

backend_key_required

403 from /forget. Only keys of backend properties can forget users. Create a backend property and call /forget from your server.

forget_forbidden

403 from /forget. The projectId in the body belongs to another account. Use a backend key from the account that owns that property.

user_id_required

400 from /forget. Send userId as a non-empty string or number.

invalid_project_id

400 from /forget. projectId must be an integer.

rate_limited

429 from /forget. Too many requests for this key in the last minute. Wait a minute, then retry.

Signing in

missing_token

401. The request has no Authorization: Bearer header. Sign in with POST /auth/login and send user.token.

invalid_token

401. The token is malformed or more than 90 days old. Sign in again.

invalid_credentials

401 from /auth/login. The email or password is wrong. The same message is used for both. There is no self-serve password reset yet.

credentials_required

400 from /auth/login. Send both email and password.

email_required

400 from /auth/register. Send email.

first_name_required

400 from /auth/register. Send firstName.

password_too_short

400 from /auth/register and /auth/password. Passwords need at least 8 characters.

email_taken

409 from /auth/register. An account already uses this email. Sign in instead.

current_password_incorrect

400 from /auth/password. currentPassword does not match.

admin_required

403. The endpoint is for the Specvista Analytics operator only and is not part of the public API.

Properties and reports

project_name_required

400 from POST /projects. Send a non-empty name.

invalid_project_type

400 from POST /projects. type must be web, mobile, backend or other, or left out for web.

project_not_found

404. No property has that id. List yours with GET /projects.

project_forbidden

403. The property belongs to another account. Use an id from your own GET /projects.

invalid_funnel_events

400 from /analytics/{id}/funnel. from and to must both be event names of up to 100 characters. Get names from /analytics/{id}/event-names.

same_funnel_events

400 from /analytics/{id}/funnel. from and to must be different events.

Responses that are not errors

• 202 {"ok":true,"skipped":true}: this browser has the sa_ignore cookie, so nothing was stored. Clear it with GET /ingest/ignore-off from that browser.
• 202 {"ok":false,"error":"userId required"} from /ingest/identify: send userId.
• 202 but the event is missing from reports: it was stored as bot or internal traffic. See the common errors in Add tracking to a Node.js server and Add tracking to a website.