Docs

Troubleshooting

Common errors, what they mean, and how to resolve them.

Fast fixes for the errors people actually hit wiring up Croombit — find your message below, apply the fix, move on.

A publishable key returns 403 identity_token_required

The call names (or resolves to) a signed-in person — email:, external_id:, … — and a pk_ key needs an identity token for that exact person. See Guide: identifying logged-in users. Anonymous device ids never need one; server-side, use an sk_ key.

Every call from my iOS/Android app returns 403

Apps send no Origin header. Create the app's pk_ key with Allow native apps enabled (Sites & API keys → New key).

A LIVE key returns 403 "origin_not_verified"

The Origin is on the site (or on the key’s allowlist) but the domain isn’t verified yet, and LIVE keys only accept verified domains. Verify it under Sites & API keys → the domain’s verify chip. TEST keys keep working meanwhile.

A publishable key returns 403 "no Origin allowlist"

pk_ keys must be Origin-restricted. Add allowed domains to the key, or verify at least one domain on the site (Sites & API keys → + domain).

Create the purpose, add at least one locale of text on its draft, and publish that version. Consent is only recorded against published versions.

The same Idempotency-Key returns 409

You reused the key with a different body. A retry must send byte-identical JSON. Keys are scoped per (site, environment).

A subject read created a blank subject

Read endpoints return 404 on unknown identifiers; only writes create. If a read created one, you were hitting a write path — check the method.

After erasure the subject is still in the vault

By design: crypto-shredding destroys the identifiers' key material (the subject is unfindable), but the anonymized event log is kept for legal defensibility.

Webhook deliveries are failing

Check the endpoint’s delivery log. Failures are retried 8 times over about 3 days (1 min → 24 h); you can replay any delivery from the console. Make sure your endpoint responds 2xx within 10 s.

I suspect an API key has leaked

Revoke it in Sites & API keys and check the org Audit log and the vault timeline for writes attributed to that apiKeyId. Create a replacement key (or rotate — the new one is valid and the old one stays until you revoke it).