Errors & rate limits

Trigv uses standard HTTP status codes. Error bodies are JSON with a message string unless validation fails (422), which includes an errors object.

Status code summary

Code	When	Example message
`200`	Duplicate `idempotency_key`	- (returns existing `event` object)
`202`	Event accepted and queued	- (returns new `event` object)
`401`	Missing/invalid Bearer key, Sanctum token on ingest, or ingest key on dashboard routes	`Invalid API key.` (or type-specific message)
`403`	Key revoked, expired, wrong scope, or inactive workspace	`This API key has been revoked.`
`404`	Channel slug not found or inactive	`Channel not found.`
`422`	Validation failed (missing `channel`, `title`, etc.)	Laravel validation errors object
`429`	Monthly workspace event cap or per-key burst limit	See below (two distinct cases)

Monthly event limit (429)

Each workspace has a monthly event allowance based on plan (stored in workspace_usage_counters). When events_count reaches events_limit, ingest returns:

Code

{
	"message": "Monthly event limit reached for this workspace."
}

Upgrade your plan or wait for the monthly counter reset. hop: 10,000/mo · leap: 40,000/mo. See pricing for current plans.

Burst rate limit (429)

Each API key is rate-limited to prevent accidental floods. Default: 60 requests per minute per key (configurable per key via rate_limit_per_minute).

Code

{
	"message": "Too many requests for this API key."
}

Backoff and retry. If you hit this often in cron loops, add jitter or batch alerts.

Idempotency

Pass the same idempotency_key on retries. The first request returns 202; subsequent identical keys return 200 with the original event and do not increment monthly usage.

Tip Distinguish 429 responses by reading message: monthly cap vs. burst throttle use different strings.