Resolución de problemas
Errores frecuentes, qué significan y cómo resolverlos.
Soluciones rápidas a los errores que la gente realmente se encuentra al integrar Croombit — busca tu mensaje, aplica la solución y sigue adelante.
Una clave publicable devuelve 403 identity_token_required
La llamada nombra (o resuelve a) una persona identificada — email:, external_id:, … — y una clave pk_ necesita un token de identidad para esa persona exacta. Consulta la Guía: identificar a usuarios con sesión iniciada. Los ids de dispositivo anónimos nunca lo necesitan; desde servidor, usa una clave sk_.
Todas las llamadas de mi app iOS/Android devuelven 403
Las apps no envían cabecera Origin. Crea la clave pk_ de la app con Allow native apps activado (Sites & API keys → New key).
Una clave LIVE devuelve 403 "origin_not_verified"
El Origin está en el sitio (o en la allowlist de la clave), pero el dominio aún no está verificado, y las claves LIVE solo aceptan dominios verificados. Verifícalo en Sites & API keys → la etiqueta verify del dominio. Mientras tanto, las claves TEST siguen funcionando.
Una clave publicable devuelve 403 "no Origin allowlist"
Las claves pk_ deben estar restringidas por Origin. Añade dominios permitidos a la clave, o verifica al menos un dominio en el sitio (Sites & API keys → + domain).
POST /v1/consent devuelve 422 "purpose has no published version"
Crea el propósito, añade al menos un idioma de texto en su borrador y publica esa versión. El consentimiento solo se registra contra versiones publicadas.
La misma Idempotency-Key devuelve 409
Has reutilizado la clave con un cuerpo distinto. Un reintento debe enviar un JSON idéntico byte a byte. Las claves tienen alcance por (sitio, entorno).
Una lectura de sujeto ha creado un sujeto en blanco
Los endpoints de lectura devuelven 404 con identificadores desconocidos; solo las escrituras crean sujetos. Si una lectura ha creado uno, estabas usando una ruta de escritura: revisa el método.
Tras un borrado, el sujeto sigue en la bóveda
Es intencionado: el crypto-shredding destruye el material de cifrado de los identificadores (el sujeto queda imposible de localizar), pero el registro de eventos anonimizado se conserva por defendibilidad legal.
Las entregas de webhook fallan
Revisa el registro de entregas del endpoint. Los fallos se reintentan 8 veces durante unos 3 días (de 1 min a 24 h); puedes reenviar cualquier entrega desde la consola. Comprueba que tu endpoint responde 2xx en menos de 10 s.
Sospecho que se ha filtrado una clave de API
Revócala en Sites & API keys y revisa el Audit log de la organización y la cronología de la bóveda en busca de escrituras atribuidas a ese apiKeyId. Crea una clave de reemplazo (o rótala: la nueva es válida y la anterior sigue funcionando hasta que la revoques).