Errores

Cuando una petición falla, la API responde con un estado HTTP y un cuerpo JSON que indica qué ha fallado. Cada cuerpo de error enlaza con su entrada en esta página.

Formato de los errores

Los errores siguen el RFC 9457 y llegan como application/problem+json. Por ejemplo, GET /v1/leads?limit=500 responde:

{
  "type": "https://totemstudio.ai/developers/errors#invalid_request",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_request",
  "request_id": "req_0f6b2c1e-8d4a-4b7e-9c3f-5a2d1e7b9c40",
  "param": "limit",
  "doc_url": "https://totemstudio.ai/developers/errors#invalid_request"
}

Campo	Qué contiene
`code`	Qué ha fallado, como un código estable. Decide según él.
`status`	El estado HTTP, repetido.
`title`	Una descripción breve en inglés, para personas. Puede cambiar, así que nunca decidas según él.
`type` y `doc_url`	Un enlace a la entrada del código más abajo.
`request_id`	El identificador de esta petición, el mismo que el de la cabecera `Totem-Request-Id`.
`param`	Solo aparece cuando falla una cabecera, un parámetro de consulta o un campo del cuerpo concreto. Lo nombra y nunca repite el valor que enviaste.

Con un error llegan estas cabeceras:

Totem-Request-Id, en todas las respuestas que envía la propia API. Regístrala y cítala cuando pidas ayuda a Soporte. Nunca nos envíes tu clave ni datos de tus clientes.
Retry-After, en cada 429 que devuelve la propia API: un número entero de segundos que debes esperar.
WWW-Authenticate: Bearer realm="Totem API", en cada 401.

Pueden aparecer códigos nuevos en cualquier momento. Trata un código que no conoces según su estado HTTP, como se describe en el apartado siguiente.

Durante la Beta, el cortafuegos situado delante de la API responde él mismo a algunas peticiones, antes de que lleguen a la API. Su respuesta no trae un cuerpo de error JSON, sino la página predeterminada del propio cortafuegos, y tampoco lleva Retry-After ni Totem-Request-Id. No intentes leer su cuerpo como JSON: trátala según su estado:

404 para una ruta fuera de /v1/, o para cualquier método distinto de GET y POST, incluidos HEAD y OPTIONS;
403 para una petición con cuerpo que no sea POST /v1/leads/search, y para un cuerpo de más de 16 KiB;
429 cuando una misma dirección envía demasiadas peticiones, por ejemplo muchas peticiones sin una clave bien formada.

Cómo tratar los errores

Decide primero según el estado HTTP y después según code:

400: corrige la petición. Si vuelves a enviar la misma petición, fallará igual. param indica qué corregir. Hay un 400 que no es culpa de tu petición: un cursor de conversaciones deja de funcionar cuando se suprime la conversación a la que apunta, así que vuelve a empezar esa lista desde la primera página, como se explica en Listas y paginación. Dos códigos piden algo más que una corrección: team_required significa que tu clave lee varios equipos y la petición debe indicar uno en Totem-Team; secret_key_in_browser significa que la clave se usó desde un navegador, así que dala por filtrada.
401: corrige la clave. No reintentes en bucle: los fallos repetidos bloquean durante un tiempo tu dirección IP o tu clave. key_expired significa que la clave se rotó y su periodo de gracia ha terminado: despliega la clave nueva.
403: el acceso está denegado por ahora. Conserva tus datos y tus cursores, y omite el equipo o el endpoint. Algunos rechazos pueden resolverse solos, como capability_disabled o un equipo cuyo acceso ha pausado Totem; otros necesitan que alguien actúe, como plan_not_entitled o ip_not_allowed; y sector_restricted no se resuelve esperando: dura mientras se aplique la política de sectores actual de Totem, y el registro de cambios recoge cualquier cambio en ella. Cada código de más abajo indica en qué caso estás. Mientras el acceso está denegado, el feed de cambios no entrega nada del equipo, tampoco eliminaciones, así que, si un rechazo dura más de lo que permite tu política de conservación, borra tu copia.
404: comprueba qué has pedido. resource_missing significa que el registro no existe, ya no está o aún no está listo; el feed de cambios entrega los registros nuevos en cuanto están listos. team_not_accessible significa que puede que la clave ya no lea el equipo: confírmalo con GET /v1/teams antes de borrar nada. Un 404 sin cuerpo de error JSON viene del cortafuegos: comprueba el método y la ruta.
409 y 410: el feed de cambios necesita que actúes. resync_required y sync_cursor_expired piden una resincronización completa. capture_not_ready te pide que esperes unos minutos, mientras los demás equipos de la clave siguen sincronizándose.
429: ve más despacio. Espera los segundos que indique Retry-After y repite la misma petición. rate_limited suele resolverse en segundos, pero tras un bloqueo por intentos fallidos dura 600 segundos. quota_exceeded dura hasta las 00:00 UTC, cuando se renueva la cuota diaria. Un 429 del cortafuegos no trae Retry-After: reintenta con espera exponencial. En Límites de frecuencia y cuota se explican los dos límites.
5xx: reintenta más tarde. Reintenta con espera exponencial y conserva tus cursores. Si sigue fallando, escribe a Soporte con el Totem-Request-Id.

En todos los casos, nunca guardes un cursor del feed de cambios tras una petición fallida.

Todos los códigos de error

Cada código tiene su propia ancla: la misma a la que apunta doc_url en la edición en inglés de esta página.

400 Petición incorrecta

invalid_request
Petición no válidatitle: "Invalid request"
Cuándo ocurre
Algo de la petición no es válido: un parámetro de consulta desconocido, repetido o fuera de rango, una cadena de consulta o un cuerpo en un endpoint que no los admite, un cursor emitido para otro endpoint, otros filtros u otro equipo, una cabecera Totem-Team mal formada o un cuerpo que no es el JSON que espera el endpoint. param indica el parámetro, la cabecera o el campo que ha fallado. Un cursor de conversaciones también se rechaza cuando se suprime la conversación a la que apunta.
Qué hacer
Corrige lo que indica param antes de reintentar: la misma petición falla igual. Si es un cursor, envía el next_cursor que recibiste del mismo endpoint, con los mismos filtros y el mismo equipo. Si se rechaza un cursor de conversaciones que no cambiaste, vuelve a empezar esa lista desde la primera página.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.
team_required
Falta el equipotitle: "Team required"
Cuándo ocurre
La clave lee más de un equipo y este endpoint lee los datos de uno, pero la petición no indica cuál.
Qué hacer
Envía el identificador del equipo (team_…, tal como aparece en GET /v1/teams) en la cabecera Totem-Team.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.
secret_key_in_browser
Clave secreta enviada desde un navegadortitle: "Secret key sent from a browser"
Cuándo ocurre
La petición llevaba una clave secreta junto con una cabecera Origin, lo que indica que salió de un navegador. Totem la rechaza sin leer nada.
Qué hacer
Llama a la API solo desde tu servidor. Si la clave ha estado en una página web, una aplicación móvil o una extensión del navegador, dala por filtrada: rótala y márcala como comprometida para que la antigua deje de funcionar al instante.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.

401 No autorizado

invalid_credentials
Credenciales no válidastitle: "Invalid credentials"
Cuándo ocurre
Falta la cabecera Authorization o está mal formada, o la clave no existe, es incorrecta o está revocada, o su integración ya no está activa.
Qué hacer
Envía Authorization: Bearer <clave> con una clave secreta vigente. No reintentes en bucle: muchos fallos desde la misma dirección IP, o con la misma clave, la bloquean durante un tiempo con 429 rate_limited.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.
key_expired
Clave caducadatitle: "Key expired"
Cuándo ocurre
La clave se rotó y su periodo de gracia ha terminado.
Qué hacer
Despliega la clave que la sustituyó: la antigua ya superó su periodo de gracia y no volverá a funcionar. Si no hay ninguna que la sustituya, crea una clave nueva en Ajustes → Desarrolladores.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.

403 Prohibido

insufficient_scope
Permisos insuficientestitle: "Insufficient scope"
Cuándo ocurre
A la clave le falta un permiso que necesita este endpoint. Todas las claves de la versión 1.0a tienen el conjunto completo de lectura, así que no debería ocurrir.
Qué hacer
Escribe a soporte e indica el Totem-Request-Id de la respuesta.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.
plan_not_entitled
El plan no incluye la APItitle: "Plan not entitled"
Cuándo ocurre
El plan de la organización no incluye ahora mismo la API de Totem.
Qué hacer
Conserva tus datos y tus cursores y deja de llamar hasta que el cliente vuelva a tener un plan con acceso a la API; después, continúa donde lo dejaste. Mientras el acceso está denegado, el feed no entrega nada de los equipos de la clave, tampoco eliminaciones: si la denegación dura más de lo que permite tu política de conservación, borra tu copia.
Reintentar
Más tarde, cuando se restablezca el acceso. Mientras, conserva tus datos y tu cursor.
ip_not_allowed
Dirección IP no permitidatitle: "IP address not allowed"
Cuándo ocurre
La clave es válida, pero la petición salió de una dirección IP que no está en la lista de IP permitidas de la integración.
Qué hacer
Llama desde una dirección permitida o pide a un administrador que añada la tuya a la lista en Ajustes → Desarrolladores.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.
team_state_restricted
Equipo restringidotitle: "Team restricted"
Cuándo ocurre
El equipo está restringido por ahora: está desactivado (por ejemplo, suspendido por impago), archivado o es solo de facturación, o tiene pausado el acceso a la API. GET /v1/teams lo sigue mostrando.
Qué hacer
Conserva los datos y el cursor del equipo, omítelo en esta ejecución y vuelve a intentarlo más tarde. Los demás equipos de la clave no se ven afectados. Mientras el equipo está restringido, el feed no entrega nada de él, tampoco eliminaciones: si la restricción dura más de lo que permite tu política de conservación, borra la copia del equipo.
Reintentar
Más tarde, cuando se restablezca el acceso. Mientras, conserva tus datos y tu cursor.
sector_restricted
Sector restringidotitle: "Sector restricted"
Cuándo ocurre
Totem no exporta los datos de este equipo por la API porque el equipo trabaja en un sector sensible, como el sanitario, en el que sus registros pueden revelar información de salud.
Qué hacer
Omite el equipo: esperar no lo cambia. El feed no entrega nada de él, tampoco eliminaciones, así que conserva lo que ya tengas solo mientras lo permita tu política de conservación y después borra la copia del equipo. Si necesitas sus datos, habla con el cliente o con Totem.
Reintentar
No. Esperar no lo cambia.
capability_disabled
Función desactivadatitle: "Capability disabled"
Cuándo ocurre
Totem ha desactivado temporalmente este endpoint para todas las claves.
Qué hacer
Conserva tus datos y tus cursores y vuelve a intentarlo más tarde; el resto de endpoints sigue funcionando.
Reintentar
Más tarde, cuando se restablezca el acceso. Mientras, conserva tus datos y tu cursor.

404 No encontrado

resource_missing
Recurso no encontradotitle: "Resource not found"
Cuándo ocurre
El registro no existe, se eliminó, pertenece a un equipo que esta clave no lee o se creó hace tan poco que Totem aún no lo ha preparado. Un GET o un POST bajo /v1/ que no corresponde a ningún endpoint también recibe este código. Cualquier otro método, y cualquier ruta fuera de /v1/, recibe un 404 simple del cortafuegos que protege la API, sin cuerpo de error ni Totem-Request-Id.
Qué hacer
Comprueba el identificador y la ruta. Si el registro se acaba de crear, no reintentes en bucle: el feed de cambios lo entregará en cuanto esté listo.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.
team_not_accessible
Equipo no accesibletitle: "Team not accessible"
Cuándo ocurre
La cabecera Totem-Team indica un equipo que esta clave no lee: uno que nunca incluyó, uno que se quitó de la clave o de la organización, o uno que se eliminó. Sin la cabecera, significa que la clave ya no lee ningún equipo.
Qué hacer
Vuelve a leer GET /v1/teams antes de actuar. Si el equipo ya no aparece, borra su copia y su cursor; si sigue apareciendo, conserva todo y vuelve a intentarlo en la siguiente ejecución.
Reintentar
Solo si GET /v1/teams sigue mostrando el equipo: entonces, en la siguiente ejecución.

409 Conflicto

resync_required
Hay que volver a sincronizartitle: "Resync required"
Cuándo ocurre
Totem no puede continuar el feed desde este cursor: los datos se restauraron desde una copia de seguridad o se detectó un hueco en los cambios del equipo.
Qué hacer
Haz una resincronización completa: olvida las versiones que guardaste del equipo, vuelve a leer el feed sin cursor y, cuando estés al día, borra los registros locales del equipo que no hayan llegado. Hasta entonces, sigue usando tu copia actual.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.
capture_not_ready
Los datos del equipo aún se están preparandotitle: "Team data is still being prepared"
Cuándo ocurre
Totem aún está preparando los datos de este equipo para la API. Ocurre una sola vez por equipo, después de que se añada por primera vez a una clave; añadirlo después a otra clave no lo repite.
Qué hacer
Conserva lo que tengas del equipo y vuelve a intentarlo dentro de unos minutos; mientras tanto, los demás equipos de la clave siguen sincronizándose.
Reintentar
Sí, más tarde: la misma petición funciona cuando los datos estén listos.

410 Ya no disponible

sync_cursor_expired
Cursor de sincronización caducadotitle: "Sync cursor expired"
Cuándo ocurre
El cursor tiene más de 30 días, contados desde el punto del feed al que llegó (o, mientras una carga inicial sigue en curso, desde que empezó).
Qué hacer
Haz una resincronización completa, como con resync_required. Para evitarlo, guarda el next_cursor de cada página, también de las vacías: el cursor de un equipo que consultas con regularidad nunca caduca.
Reintentar
No. La misma petición falla igual hasta que corrijas la causa.

429 Demasiadas peticiones

rate_limited
Límite de frecuencia superadotitle: "Rate limited"
Cuándo ocurre
La clave ha superado su límite de frecuencia (elementos por minuto), o demasiados intentos de autenticación fallidos desde esta dirección IP o con esta clave la han bloqueado durante un tiempo.
Qué hacer
Espera los segundos que indica Retry-After y repite la misma petición. Cada petición aparta su limit completo al empezar y devuelve lo que no usa, así que con un limit más pequeño avanzas aunque quede poco margen.
Reintentar
Sí, tras los segundos que indica Retry-After.
quota_exceeded
Cuota diaria superadatitle: "Daily quota exceeded"
Cuándo ocurre
La clave ha consumido su cuota diaria de elementos. Para la cuota cuenta cada elemento que devuelven el feed de cambios y todas las listas, incluidas GET /v1/teams, GET /v1/members, GET /v1/booking_services y las actividades de un lead. La cuota se renueva a las 00:00 UTC.
Qué hacer
Deja de sincronizar hasta las 00:00 UTC (Retry-After indica los segundos que faltan) y continúa entonces con el mismo cursor: no se pierde nada. Las peticiones de un solo registro, como GET /v1/leads/{id}, la búsqueda y GET /v1/me no cuentan para la cuota y siguen funcionando.
Reintentar
Sí, tras los segundos que indica Retry-After.

500 Error interno del servidor

internal_error
Error internotitle: "Internal error"
Cuándo ocurre
Algo ha fallado dentro de Totem al responder a esta petición.
Qué hacer
Reintenta con una espera exponencial. Si sigue fallando, escribe a soporte e indica el Totem-Request-Id.
Reintentar
Sí, con espera exponencial.

503 Servicio no disponible

api_disabled
API desactivadatitle: "API disabled"
Cuándo ocurre
Totem ha desactivado temporalmente la API para todas las claves.
Qué hacer
Conserva tus datos y tus cursores y reintenta más tarde con una espera exponencial.
Reintentar
Sí, con espera exponencial.
service_unavailable
Servicio no disponibletitle: "Service unavailable"
Cuándo ocurre
Reservado: la API no devuelve hoy este código. Un 503 del balanceador de carga o de la plataforma que aloja la API llega sin cuerpo de error; trátalo como este código.
Qué hacer
Reintenta con una espera exponencial; tus datos y tus cursores siguen siendo válidos.
Reintentar
Sí, con espera exponencial.

Formato de los errores

Cómo tratar los errores

Todos los códigos de error

400 Petición incorrecta

`invalid_request`

`team_required`

`secret_key_in_browser`

401 No autorizado

`invalid_credentials`

`key_expired`

403 Prohibido

`insufficient_scope`

`plan_not_entitled`

`ip_not_allowed`

`team_state_restricted`

`sector_restricted`

`capability_disabled`

404 No encontrado

`resource_missing`

`team_not_accessible`

409 Conflicto

`resync_required`

`capture_not_ready`

410 Ya no disponible

`sync_cursor_expired`

429 Demasiadas peticiones

`rate_limited`

`quota_exceeded`

500 Error interno del servidor

`internal_error`

503 Servicio no disponible

`api_disabled`

`service_unavailable`