API Errors#

The /api/ingest endpoint is intentionally simple, but it still returns descriptive errors when something goes wrong. This page lists every response and resolution.

Error Response Format#

{
  "error": "Invalid API token"
}

or, for validation failures:

{
  "message": "The data.visitor_fingerprint field is required."
}

Status Codes#

Status	Error	Meaning	Resolution
`400 Bad Request`	Validation message	Missing or malformed `data` fields.	Supply required fields, ensure payload uses correct types.
`401 Unauthorized`	`Missing API token`	`X-API-Token` header absent and `token` missing in body.	Add header `X-API-Token: <token>` or include `token` in JSON payload.
`401 Unauthorized`	`Invalid API token`	Token not found or disabled.	Use a valid token from the dashboard, double-check environment variables.
`403 Forbidden`	`Revenue events require secret token`	Attempted to send `type: revenue` with a public token.	Use `sec_...` tokens for revenue calls.
`429 Too Many Requests`	`Rate limited`	Token exceeded rate limits. `Retry-After` header returned.	Honor `Retry-After`, implement exponential backoff (built into SDKs).
`500 Internal Server Error`	Varies	Unexpected server error.	Retry with backoff; if persistent, contact support with timestamps & payloads (excluding secrets).

Validation Errors#

Pageviews & Events#

The data.visitor_fingerprint field is required.
The data.session_id field is required.
The data.event_name field is required. (events only)

Identify#

The data.customer_id field is required.

Revenue#

visitor_fingerprint is required.
session_id is required.
customer_id is required.
amount must be a positive number.
transaction_id is required.
event_type must be one of: purchase, subscription, renewal, upgrade, downgrade, churn, refund.
mrr_impact must be a number. (if provided)

The revenue SDK throws these before the request is sent, making them easier to catch during development.

Troubleshooting Checklist#

Confirm you are using the correct token prefix (pub_ vs sec_).
Enable debug: true to see the full payload and response in the console (core SDK).
Inspect the browser Network tab or server logs for the exact response body.
Retry with exponential backoff when 429 or transient 5xx errors occur.
For webhooks, ensure your handler responds with a 2xx status after calling revenue.track().

Still stuck? Contact support@pulsora.co with:

Timestamp (UTC)
Token (first 6 characters)
Event type
Response body
Request ID (from response headers, if available)

Return to the REST API reference → for payload examples.