Errors

Sankofa returns errors in a uniform JSON shape across every endpoint. The HTTP status code tells you what kind of error; the error field tells you what specifically went wrong.

The error shape

{
"ok": false,
"error": "Human-readable message"
}

Every endpoint that returns an error returns this shape. There's no machine-readable error code — for now, match on the HTTP status code and (optionally) parse the error string.

Status codes

Common error messages

The error field is a free-form English string. The most common values you'll encounter:

Authentication

Ingestion

Rate limit + capacity

Dashboard / management

How to handle each class

4xx — your request

These are caused by something your client sent. Don't retry. Fix the request and try again.

• 400 — fix the body
• 401 — fix the auth header
• 403 — fix the key, the Origin, the IP allowlist, or the role
• 404 — fix the URL
• 409 — read the error message; usually means a unique constraint

429 — rate-limited

Back off and retry. See Rate limits for the recommended pattern.

5xx — engine-side

These are transient. Retry with exponential backoff (1s, 2s, 4s, 8s, 16s, capped at 60s). If the issue persists past a few minutes, contact support with the timestamp + request body.

• 500 — engine bug; rare but possible
• 503 — async buffer full; the engine self-recovers within seconds

202 — accepted but discarded

Not an error per se — the engine accepted the request and silently discarded it (typically because the distinct_id was unidentifiable garbage). Response body is {"ok": true, "status": "discarded"} or "discarded_all" (for batches).

If you see this consistently, your SDK's distinct-ID generation is producing values that match the engine's garbage-detection heuristic (very short strings, or strings containing common HTTP-header values like "gzip" or "*/*"). Switch to a UUID-based generator.

Idempotency

Sankofa does not support client-supplied event IDs for idempotency on ingestion. Every track / people / alias call generates a new server-side ID — retrying a request that succeeded creates duplicate events.

For ingestion at-least-once delivery this is the right tradeoff (the SDK queues and retries on failure), but for custom HTTP integrations you must avoid retrying on 2xx responses. Only retry on 429, 503, and network failures.

Diagnostic recommendations

When something goes wrong:

1. Check the status + error

   The status alone narrows it to a class; the error string usually points to the exact issue.

2. Verify the request body in the dashboard

   /dashboard/<project>/live-events shows accepted requests. If your event isn't there, the engine never accepted it — check the response body for the rejection reason.

3. Capture and report request IDs for 5xx

   The engine includes a request_id in 500-class responses (in headers when present). Include this in support tickets — it lets us trace through the engine logs.

4. Test against the test environment first

   Switch to sk_test_* and the test environment for diagnostics — billing quotas don't apply, and the dashboard shows test events on a separate filter.

What's next