API Reference

Error codes

Every failed Ingest or apps statistics request returns JSON with a stable machine-readable code. Check code first — message is human-friendly and may change copy edits.

Error shape

Error payloadjson

{
  "error": {
    "code": "forbidden_event_type",
    "message": "eventType 'deploy.shipped' is not in this app's whitelist.",
    "requestId": "req_01HP3K5V4J3M9NVT8XZKQ9YQ2E",
    "docsUrl": "https://wepeople.app/docs/reference/errors"
  }
}

Cite requestId in support tickets. docsUrl deep-links to this page.

Code table

Code	HTTP	When
missing_authorization	401	No Authorization header present.
invalid_key	401	Key does not exist or is malformed.
key_revoked	401	Key was revoked in the Developer tab.
key_expired	401	Key is past its expiresAt.
plan_disabled	402	Plan does not include the developer API.
quota_exceeded	402	Monthly event quota (maxEventsPerMonth) exhausted.
rate_limited	429	Per-key (60/s) or per-org (600/s) burst exceeded.
forbidden_event_type	403	eventType is not in the app's whitelist.
invalid_body	400	Validation failed; message lists first issues.
batch_too_large	413	Body > 1 MB or batch > 100 events.
missing_actor	400	actor lacks workerId, externalId, and email.
worker_not_found	404	workerId did not resolve for this org.
internal_error	500	Unexpected failure; retry with backoff.

Handling tips

rate_limited — respect Retry-After; the SDK backs off automatically.
forbidden_event_type — add the type to your app whitelist in Organization → Developer.
quota_exceeded — upgrade plan or wait for the monthly reset.
internal_error — retry with exponential backoff; include requestId if it persists.

Partial batch failures on POST events return 207 with per-row codes in results.rejected — not the top-level error envelope.