[{"data":1,"prerenderedAt":756},["ShallowReactive",2],{"developers:\u002Fdevelopers\u002Fes\u002Ferrors":3},{"doc":4,"lang":445,"nav":456,"alternatePath":557,"policy":558,"specVersion":602,"reference":603,"layout":748,"toc":749,"prev":753,"next":754,"operations":755,"overview":7,"heroExample":7},{"id":5,"title":6,"apiTag":7,"body":8,"description":442,"draft":443,"extension":444,"lang":445,"meta":446,"navTitle":7,"navigation":447,"order":448,"path":449,"rawbody":450,"section":451,"seo":452,"stem":453,"translationKey":454,"version":7,"__hash__":455},"developers_es\u002Fdevelopers\u002Fes\u002Ferrors.md","Errores",null,{"type":9,"value":10,"toc":435},"minimark",[11,15,20,32,42,129,132,165,168,177,224,228,234,418,421,425,431],[12,13,14],"p",{},"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.",[16,17,19],"h2",{"id":18},"formato-de-los-errores","Formato de los errores",[12,21,22,23,27,28,31],{},"Los errores siguen el RFC 9457 y llegan como ",[24,25,26],"code",{},"application\u002Fproblem+json",". Por ejemplo, ",[24,29,30],{},"GET \u002Fv1\u002Fleads?limit=500"," responde:",[33,34,40],"pre",{"className":35,"code":37,"language":38,"meta":39},[36],"language-json","{\n  \"type\": \"https:\u002F\u002Ftotemstudio.ai\u002Fdevelopers\u002Ferrors#invalid_request\",\n  \"title\": \"Invalid request\",\n  \"status\": 400,\n  \"code\": \"invalid_request\",\n  \"request_id\": \"req_0f6b2c1e-8d4a-4b7e-9c3f-5a2d1e7b9c40\",\n  \"param\": \"limit\",\n  \"doc_url\": \"https:\u002F\u002Ftotemstudio.ai\u002Fdevelopers\u002Ferrors#invalid_request\"\n}\n","json","",[24,41,37],{"__ignoreMap":39},[43,44,45,58],"table",{},[46,47,48],"thead",{},[49,50,51,55],"tr",{},[52,53,54],"th",{},"Campo",[52,56,57],{},"Qué contiene",[59,60,61,71,81,91,105,119],"tbody",{},[49,62,63,68],{},[64,65,66],"td",{},[24,67,24],{},[64,69,70],{},"Qué ha fallado, como un código estable. Decide según él.",[49,72,73,78],{},[64,74,75],{},[24,76,77],{},"status",[64,79,80],{},"El estado HTTP, repetido.",[49,82,83,88],{},[64,84,85],{},[24,86,87],{},"title",[64,89,90],{},"Una descripción breve en inglés, para personas. Puede cambiar, así que nunca decidas según él.",[49,92,93,102],{},[64,94,95,98,99],{},[24,96,97],{},"type"," y ",[24,100,101],{},"doc_url",[64,103,104],{},"Un enlace a la entrada del código más abajo.",[49,106,107,112],{},[64,108,109],{},[24,110,111],{},"request_id",[64,113,114,115,118],{},"El identificador de esta petición, el mismo que el de la cabecera ",[24,116,117],{},"Totem-Request-Id",".",[49,120,121,126],{},[64,122,123],{},[24,124,125],{},"param",[64,127,128],{},"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.",[12,130,131],{},"Con un error llegan estas cabeceras:",[133,134,135,147,157],"ul",{},[136,137,138,140,141,146],"li",{},[24,139,117],{},", en todas las respuestas que envía la propia API. Regístrala y cítala cuando pidas ayuda a ",[142,143,145],"a",{"href":144},"\u002Fdevelopers\u002Fes\u002Fsupport","Soporte",". Nunca nos envíes tu clave ni datos de tus clientes.",[136,148,149,152,153,156],{},[24,150,151],{},"Retry-After",", en cada ",[24,154,155],{},"429"," que devuelve la propia API: un número entero de segundos que debes esperar.",[136,158,159,152,162,118],{},[24,160,161],{},"WWW-Authenticate: Bearer realm=\"Totem API\"",[24,163,164],{},"401",[12,166,167],{},"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.",[12,169,170,171,173,174,176],{},"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 ",[24,172,151],{}," ni ",[24,175,117],{},". No intentes leer su cuerpo como JSON: trátala según su estado:",[133,178,179,203,219],{},[136,180,181,184,185,188,189,98,192,195,196,98,199,202],{},[24,182,183],{},"404"," para una ruta fuera de ",[24,186,187],{},"\u002Fv1\u002F",", o para cualquier método distinto de ",[24,190,191],{},"GET",[24,193,194],{},"POST",", incluidos ",[24,197,198],{},"HEAD",[24,200,201],{},"OPTIONS",";",[136,204,205,208,209,212,213,218],{},[24,206,207],{},"403"," para una petición con cuerpo que no sea ",[24,210,211],{},"POST \u002Fv1\u002Fleads\u002Fsearch",", y para un cuerpo de más de ",[214,215],"api-const",{"divide":216,"name":217},"1024","REQUEST_BODY_MAX_BYTES"," KiB;",[136,220,221,223],{},[24,222,155],{}," cuando una misma dirección envía demasiadas peticiones, por ejemplo muchas peticiones sin una clave bien formada.",[16,225,227],{"id":226},"cómo-tratar-los-errores","Cómo tratar los errores",[12,229,230,231,233],{},"Decide primero según el estado HTTP y después según ",[24,232,24],{},":",[133,235,236,269,281,310,337,364,404],{},[136,237,238,245,246,248,249,251,252,256,257,260,261,264,265,268],{},[239,240,241,244],"strong",{},[24,242,243],{},"400",": corrige la petición."," Si vuelves a enviar la misma petición, fallará igual. ",[24,247,125],{}," indica qué corregir. Hay un ",[24,250,243],{}," 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 ",[142,253,255],{"href":254},"\u002Fdevelopers\u002Fes\u002Fpagination#p%C3%A1ginas-y-cursores","Listas y paginación",". Dos códigos piden algo más que una corrección: ",[24,258,259],{},"team_required"," significa que tu clave lee varios equipos y la petición debe indicar uno en ",[24,262,263],{},"Totem-Team","; ",[24,266,267],{},"secret_key_in_browser"," significa que la clave se usó desde un navegador, así que dala por filtrada.",[136,270,271,276,277,280],{},[239,272,273,275],{},[24,274,164],{},": corrige la clave."," No reintentes en bucle: los fallos repetidos bloquean durante un tiempo tu dirección IP o tu clave. ",[24,278,279],{},"key_expired"," significa que la clave se rotó y su periodo de gracia ha terminado: despliega la clave nueva.",[136,282,283,288,289,292,293,296,297,300,301,304,305,309],{},[239,284,285,287],{},[24,286,207],{},": 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 ",[24,290,291],{},"capability_disabled"," o un equipo cuyo acceso ha pausado Totem; otros necesitan que alguien actúe, como ",[24,294,295],{},"plan_not_entitled"," o ",[24,298,299],{},"ip_not_allowed","; y ",[24,302,303],{},"sector_restricted"," no se resuelve esperando: dura mientras se aplique la política de sectores actual de Totem, y el ",[142,306,308],{"href":307},"\u002Fdevelopers\u002Fes\u002Fchangelog","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.",[136,311,312,317,318,321,322,325,326,333,334,336],{},[239,313,314,316],{},[24,315,183],{},": comprueba qué has pedido."," ",[24,319,320],{},"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. ",[24,323,324],{},"team_not_accessible"," significa que puede que la clave ya no lea el equipo: ",[142,327,329,330],{"href":328},"\u002Fdevelopers\u002Fes\u002Fsync#cuando-cambian-los-equipos","confírmalo con ",[24,331,332],{},"GET \u002Fv1\u002Fteams"," antes de borrar nada. Un ",[24,335,183],{}," sin cuerpo de error JSON viene del cortafuegos: comprueba el método y la ruta.",[136,338,339,317,348,98,351,354,355,359,360,363],{},[239,340,341,98,344,347],{},[24,342,343],{},"409",[24,345,346],{},"410",": el feed de cambios necesita que actúes.",[24,349,350],{},"resync_required",[24,352,353],{},"sync_cursor_expired"," piden una ",[142,356,358],{"href":357},"\u002Fdevelopers\u002Fes\u002Fsync#resincronizaci%C3%B3n-completa","resincronización completa",". ",[24,361,362],{},"capture_not_ready"," te pide que esperes unos minutos, mientras los demás equipos de la clave siguen sincronizándose.",[136,365,366,371,372,374,375,378,379,383,384,388,389,392,393,395,396,398,399,403],{},[239,367,368,370],{},[24,369,155],{},": ve más despacio."," Espera los segundos que indique ",[24,373,151],{}," y repite la misma petición. ",[24,376,377],{},"rate_limited"," suele resolverse en segundos, pero tras un ",[142,380,382],{"href":381},"\u002Fdevelopers\u002Fes\u002Fauthentication#intentos-fallidos","bloqueo por intentos fallidos"," dura ",[214,385],{"divide":386,"name":387},"1000","AUTH_FAILURE_LIMITS.banMs"," segundos. ",[24,390,391],{},"quota_exceeded"," dura hasta las 00:00 UTC, cuando se renueva la cuota diaria. Un ",[24,394,155],{}," del cortafuegos no trae ",[24,397,151],{},": reintenta con espera exponencial. En ",[142,400,402],{"href":401},"\u002Fdevelopers\u002Fes\u002Frate-limits","Límites de frecuencia y cuota"," se explican los dos límites.",[136,405,406,412,413,415,416,118],{},[239,407,408,411],{},[24,409,410],{},"5xx",": reintenta más tarde."," Reintenta con espera exponencial y conserva tus cursores. Si sigue fallando, escribe a ",[142,414,145],{"href":144}," con el ",[24,417,117],{},[12,419,420],{},"En todos los casos, nunca guardes un cursor del feed de cambios tras una petición fallida.",[16,422,424],{"id":423},"todos-los-códigos-de-error","Todos los códigos de error",[12,426,427,428,430],{},"Cada código tiene su propia ancla: la misma a la que apunta ",[24,429,101],{}," en la edición en inglés de esta página.",[432,433],"dev-error-catalog",{":example":434},"false",{"title":39,"searchDepth":436,"depth":436,"links":437},3,[438,440,441],{"id":18,"depth":439,"text":19},2,{"id":226,"depth":439,"text":227},{"id":423,"depth":439,"text":424},"El formato de los errores, cómo debe tratar tu integración cada tipo de error y todos los códigos de error, con cuándo ocurren y qué hacer.",false,"md","es",{},true,"20","\u002Fdevelopers\u002Fes\u002Ferrors","---\ntitle: Errores\ndescription: El formato de los errores, cómo debe tratar tu integración cada tipo de error y todos los códigos de error, con cuándo ocurren y qué hacer.\nsection: reference\norder: 20\ntranslationKey: errors\nlang: es\ndraft: false\n---\n\nCuando 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.\n\n## Formato de los errores\n\nLos errores siguen el RFC 9457 y llegan como `application\u002Fproblem+json`. Por ejemplo, `GET \u002Fv1\u002Fleads?limit=500` responde:\n\n```json\n{\n  \"type\": \"https:\u002F\u002Ftotemstudio.ai\u002Fdevelopers\u002Ferrors#invalid_request\",\n  \"title\": \"Invalid request\",\n  \"status\": 400,\n  \"code\": \"invalid_request\",\n  \"request_id\": \"req_0f6b2c1e-8d4a-4b7e-9c3f-5a2d1e7b9c40\",\n  \"param\": \"limit\",\n  \"doc_url\": \"https:\u002F\u002Ftotemstudio.ai\u002Fdevelopers\u002Ferrors#invalid_request\"\n}\n```\n\n| Campo | Qué contiene |\n|---|---|\n| `code` | Qué ha fallado, como un código estable. Decide según él. |\n| `status` | El estado HTTP, repetido. |\n| `title` | Una descripción breve en inglés, para personas. Puede cambiar, así que nunca decidas según él. |\n| `type` y `doc_url` | Un enlace a la entrada del código más abajo. |\n| `request_id` | El identificador de esta petición, el mismo que el de la cabecera `Totem-Request-Id`. |\n| `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. |\n\nCon un error llegan estas cabeceras:\n\n- `Totem-Request-Id`, en todas las respuestas que envía la propia API. Regístrala y cítala cuando pidas ayuda a [Soporte](\u002Fdevelopers\u002Fes\u002Fsupport). Nunca nos envíes tu clave ni datos de tus clientes.\n- `Retry-After`, en cada `429` que devuelve la propia API: un número entero de segundos que debes esperar.\n- `WWW-Authenticate: Bearer realm=\"Totem API\"`, en cada `401`.\n\nPueden 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.\n\nDurante 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:\n\n- `404` para una ruta fuera de `\u002Fv1\u002F`, o para cualquier método distinto de `GET` y `POST`, incluidos `HEAD` y `OPTIONS`;\n- `403` para una petición con cuerpo que no sea `POST \u002Fv1\u002Fleads\u002Fsearch`, y para un cuerpo de más de :api-const{name=\"REQUEST_BODY_MAX_BYTES\" divide=\"1024\"} KiB;\n- `429` cuando una misma dirección envía demasiadas peticiones, por ejemplo muchas peticiones sin una clave bien formada.\n\n## Cómo tratar los errores\n\nDecide primero según el estado HTTP y después según `code`:\n\n- **`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](\u002Fdevelopers\u002Fes\u002Fpagination#páginas-y-cursores). 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.\n- **`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.\n- **`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](\u002Fdevelopers\u002Fes\u002Fchangelog) 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.\n- **`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 \u002Fv1\u002Fteams`](\u002Fdevelopers\u002Fes\u002Fsync#cuando-cambian-los-equipos) antes de borrar nada. Un `404` sin cuerpo de error JSON viene del cortafuegos: comprueba el método y la ruta.\n- **`409` y `410`: el feed de cambios necesita que actúes.** `resync_required` y `sync_cursor_expired` piden una [resincronización completa](\u002Fdevelopers\u002Fes\u002Fsync#resincronización-completa). `capture_not_ready` te pide que esperes unos minutos, mientras los demás equipos de la clave siguen sincronizándose.\n- **`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](\u002Fdevelopers\u002Fes\u002Fauthentication#intentos-fallidos) dura :api-const{name=\"AUTH_FAILURE_LIMITS.banMs\" divide=\"1000\"} 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](\u002Fdevelopers\u002Fes\u002Frate-limits) se explican los dos límites.\n- **`5xx`: reintenta más tarde.** Reintenta con espera exponencial y conserva tus cursores. Si sigue fallando, escribe a [Soporte](\u002Fdevelopers\u002Fes\u002Fsupport) con el `Totem-Request-Id`.\n\nEn todos los casos, nunca guardes un cursor del feed de cambios tras una petición fallida.\n\n## Todos los códigos de error\n\nCada 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.\n\n::dev-error-catalog{:example=\"false\"}\n::\n","reference",{"title":6,"description":442},"developers\u002Fes\u002Ferrors","errors","Cr3glC4Vp8hq9rFRh84LYA2hqIlwi_3IAg2fu1jJaVU",[457,472,498,541],{"section":458,"items":459},"start",[460,464,468],{"path":461,"title":462,"description":463},"\u002Fdevelopers\u002Fes","Introducción","Lee desde tus propios sistemas los leads, las llamadas, las conversaciones y las citas de tus equipos de Totem, y mantén una copia sincronizada.",{"path":465,"title":466,"description":467},"\u002Fdevelopers\u002Fes\u002Fquickstart","Inicio rápido","Haz tus primeras peticiones a la API de Totem en unos minutos. Comprueba tu clave, busca tu equipo, lista leads e inicia una sincronización.",{"path":469,"title":470,"description":471},"\u002Fdevelopers\u002Fes\u002Fauthentication","Autenticación","Las claves secretas y dónde pueden guardarse, la cabecera Totem-Team de las claves con varios equipos, la lista de IP permitidas y cómo rotar o revocar una clave.",{"section":473,"items":474},"guides",[475,479,483,486,490,494],{"path":476,"title":477,"description":478},"\u002Fdevelopers\u002Fes\u002Ftypescript","SDK de TypeScript","Usa el cliente oficial de TypeScript para leer tus datos de Totem, paginar listas y gestionar errores de la API desde tu servidor.",{"path":480,"title":481,"description":482},"\u002Fdevelopers\u002Fes\u002Fsync","Sincroniza una copia","Copia un equipo con el feed de cambios y mantén la copia al día. Aplica las páginas sin riesgos, recupérate de los errores y parte de un cliente de referencia que Totem prueba.",{"path":484,"title":255,"description":485},"\u002Fdevelopers\u002Fes\u002Fpagination","Cómo devuelven los endpoints de lista los registros página a página, cómo leer todas las páginas y qué orden y qué filtros admite una lista.",{"path":487,"title":488,"description":489},"\u002Fdevelopers\u002Fes\u002Fcoverage","Cobertura de los datos","Qué registra Totem, desde cuándo y cómo distinguir un valor vacío de un dato que nunca se registró.",{"path":491,"title":492,"description":493},"\u002Fdevelopers\u002Fes\u002Ftesting","Pruebas y puesta en producción","Cómo construir y probar una integración con seguridad mientras la API no tiene entorno de pruebas, y qué comprobar antes de pasar a producción.",{"path":495,"title":496,"description":497},"\u002Fdevelopers\u002Fes\u002Fsecurity","Seguridad y datos personales","Cómo protege Totem las claves de la API y los datos que sirve, qué registra de cada clave, dónde funciona la API y qué hacer con los datos personales que copias.",{"section":451,"items":499},[500,504,505,507,512,517,522,527,532,537],{"path":501,"title":502,"description":503},"\u002Fdevelopers\u002Fes\u002Fconventions","Convenciones","La notación de esta documentación y las reglas que siguen todas las respuestas: identificadores, fechas, valores vacíos, importes, enumeraciones, versiones, estabilidad, errores y textos no fiables.",{"path":449,"title":6,"description":442},{"path":401,"title":402,"description":506},"Cuánto puede leer una clave por minuto y por día, qué cuenta para cada límite, cómo reintentar tras un 429 y cuánto tarda una carga inicial.",{"path":508,"title":509,"description":510,"apiTag":511},"\u002Fdevelopers\u002Fes\u002Freference-account","Cuenta, equipos y miembros","Comprueba que una clave funciona y qué puede leer, lista sus equipos con su zona horaria, lista los miembros de cada equipo y comprueba que la API está funcionando.","account",{"path":513,"title":514,"description":515,"apiTag":516},"\u002Fdevelopers\u002Fes\u002Freference-leads","Leads, tableros y actividades","Lista, obtén y busca los leads y los clientes de un equipo, lee las actividades de cada lead y lista los tableros y las etapas por los que pasan.","leads",{"path":518,"title":519,"description":520,"apiTag":521},"\u002Fdevelopers\u002Fes\u002Freference-calls","Llamadas","Lista y obtén las llamadas de un equipo, con su dirección, su horario y un resultado normalizado. Sin grabaciones ni transcripciones.","calls",{"path":523,"title":524,"description":525,"apiTag":526},"\u002Fdevelopers\u002Fes\u002Freference-conversations","Conversaciones","Lista y obtén las conversaciones de un equipo en todos los canales, con su estado, la persona asignada, si una persona ha tomado el control y cuándo llegaron y salieron los últimos mensajes. Nunca el contenido de los mensajes.","conversations",{"path":528,"title":529,"description":530,"apiTag":531},"\u002Fdevelopers\u002Fes\u002Freference-bookings","Citas y servicios","Lista y obtén las citas de un equipo, y lista los servicios que pueden reservar sus clientes.","bookings",{"path":533,"title":534,"description":535,"apiTag":536},"\u002Fdevelopers\u002Fes\u002Freference-sync","Feed de cambios","Un único endpoint que copia un equipo y, después, devuelve cada cambio, página a página.","sync",{"path":538,"title":539,"description":540},"\u002Fdevelopers\u002Fes\u002Fobjects","Todos los objetos","Todos los objetos que devuelve la API, campo a campo, con un ejemplo de cada uno.",{"section":542,"items":543},"resources",[544,547,549,553],{"path":307,"title":545,"description":546},"Registro de cambios","Los cambios de la API de Totem, del más reciente al más antiguo, cada uno bajo la fecha en que se publicó.",{"path":144,"title":145,"description":548},"Cómo pedir ayuda con la API de Totem, qué incluir en una solicitud y qué hacer si se filtra una clave.",{"path":550,"title":551,"description":552},"\u002Fdevelopers\u002Fes\u002Fglossary","Glosario","Los términos de esta documentación, definidos en un solo lugar, cada uno con un enlace a la página que lo explica.",{"path":554,"title":555,"description":556},"\u002Fdevelopers\u002Fes\u002Ffaq","Preguntas frecuentes","Respuestas breves a las preguntas más habituales sobre la API de Totem, con enlaces a los detalles.","\u002Fdevelopers\u002Ferrors",{"ACTIVATION_MARGIN_MS":559,"ADMIN_ACCESS_DISCLOSURE_VERSION":560,"AUDIT_RETENTION_DAYS":561,"AUTH_FAILURE_LIMITS":562,"CAPTURE_LAG_FLOOR_MS":566,"CAPTURE_LAG_P99_MS":7,"CURSOR_MAX_AGE_DAYS":567,"DIRTY_TTL_DAYS":567,"FAMILY_TEAM_SCOPE":568,"FAMILY_TEAM_SCOPE_OPTIONS":569,"FEED_SETTLE_LAG_MS":571,"GATE_REFRESH_MS":559,"INTEGRATION_NAME_LENGTH":572,"INTEGRATION_PURPOSE_LENGTH":574,"KEY_CACHE_TTL_MS":577,"KEY_STATS_RETENTION_DAYS":578,"LEAD_RESPONSE_READ_BUDGET":579,"LIST_SCAN_MAX":582,"MAX_FAMILY_INTEGRATION_TEAMS":567,"MAX_INTEGRATIONS_PER_FAMILY":583,"MAX_IP_ALLOWLIST":564,"PAGE_LIMIT":584,"PLATFORM_CONFIG_TTL_MS":587,"REMOVAL_RETENTION_DAYS":588,"REQUEST_BODY_MAX_BYTES":589,"ROLL_GRACE_DEFAULT_HOURS":590,"ROLL_GRACE_HOURS":591,"SEARCH_MAX_RESULTS":583,"SENSITIVE_SECTOR_POLICY":594,"SENSITIVE_SECTOR_POLICY_OPTIONS":595,"SYNC_DAILY_BUDGET":597,"SYNC_VELOCITY":599,"TEAM_CACHE_TTL_MS":601},60000,"2026-10-17",365,{"perIpPerMinute":563,"perLookupIdPerMinute":564,"banMs":565},60,20,600000,300000,30,"explicit_list",[568,570],"all_family_teams",10000,{"min":439,"max":573},80,{"min":575,"max":576},1,280,5000,90,{"conversations":564,"messageReads":580,"calls":581},200,50,1000,10,{"default":585,"max":586},25,100,15000,45,16384,24,[592,575,590,593],0,168,"exclude",[594,596],"allow",{"floor":598,"recordsMultiplier":436},250000,{"perMinute":600,"burst":571},2000,30000,"1.0a",{"operations":604,"schemas":605,"errors":606,"commonErrors":743,"defaultStability":744,"policy":558,"problemExample":745},[],[],[607,616,621,626,634,639,647,654,659,665,671,676,682,689,696,703,709,717,722,730,737],{"code":608,"status":609,"title":610,"wireTitle":611,"action":612,"description":613,"fix":614,"retryable":443,"retry":615},"invalid_request",400,"Petición no válida","Invalid request","fix_request","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.","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.","no",{"code":259,"status":609,"title":617,"wireTitle":618,"action":612,"description":619,"fix":620,"retryable":443,"retry":615},"Falta el equipo","Team required","La clave lee más de un equipo y este endpoint lee los datos de uno, pero la petición no indica cuál.","Envía el identificador del equipo (`team_…`, tal como aparece en `GET \u002Fv1\u002Fteams`) en la cabecera `Totem-Team`.",{"code":267,"status":609,"title":622,"wireTitle":623,"action":612,"description":624,"fix":625,"retryable":443,"retry":615},"Clave secreta enviada desde un navegador","Secret key sent from a browser","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.","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.",{"code":627,"status":628,"title":629,"wireTitle":630,"action":631,"description":632,"fix":633,"retryable":443,"retry":615},"invalid_credentials",401,"Credenciales no válidas","Invalid credentials","check_credentials","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.","Envía `Authorization: Bearer \u003Cclave>` 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`.",{"code":279,"status":628,"title":635,"wireTitle":636,"action":631,"description":637,"fix":638,"retryable":443,"retry":615},"Clave caducada","Key expired","La clave se rotó y su periodo de gracia ha terminado.","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.",{"code":640,"status":641,"title":642,"wireTitle":643,"action":644,"description":645,"fix":646,"retryable":443,"retry":615},"insufficient_scope",403,"Permisos insuficientes","Insufficient scope","contact_support","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.","Escribe a soporte e indica el `Totem-Request-Id` de la respuesta.",{"code":295,"status":641,"title":648,"wireTitle":649,"action":650,"description":651,"fix":652,"retryable":447,"retry":653},"El plan no incluye la API","Plan not entitled","keep_and_retry","El plan de la organización no incluye ahora mismo la API de Totem.","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.","restored",{"code":299,"status":641,"title":655,"wireTitle":656,"action":631,"description":657,"fix":658,"retryable":443,"retry":615},"Dirección IP no permitida","IP address not allowed","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.","Llama desde una dirección permitida o pide a un administrador que añada la tuya a la lista en Ajustes → Desarrolladores.",{"code":660,"status":641,"title":661,"wireTitle":662,"action":650,"description":663,"fix":664,"retryable":447,"retry":653},"team_state_restricted","Equipo restringido","Team restricted","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 \u002Fv1\u002Fteams` lo sigue mostrando.","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.",{"code":303,"status":641,"title":666,"wireTitle":667,"action":650,"description":668,"fix":669,"retryable":443,"retry":670},"Sector restringido","Sector restricted","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.","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.","blocked",{"code":291,"status":641,"title":672,"wireTitle":673,"action":650,"description":674,"fix":675,"retryable":447,"retry":653},"Función desactivada","Capability disabled","Totem ha desactivado temporalmente este endpoint para todas las claves.","Conserva tus datos y tus cursores y vuelve a intentarlo más tarde; el resto de endpoints sigue funcionando.",{"code":320,"status":677,"title":678,"wireTitle":679,"action":612,"description":680,"fix":681,"retryable":443,"retry":615},404,"Recurso no encontrado","Resource not found","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 `\u002Fv1\u002F` que no corresponde a ningún endpoint también recibe este código. Cualquier otro método, y cualquier ruta fuera de `\u002Fv1\u002F`, recibe un `404` simple del cortafuegos que protege la API, sin cuerpo de error ni `Totem-Request-Id`.","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.",{"code":324,"status":677,"title":683,"wireTitle":684,"action":685,"description":686,"fix":687,"retryable":443,"retry":688},"Equipo no accesible","Team not accessible","drop_team","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.","Vuelve a leer `GET \u002Fv1\u002Fteams` 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.","confirm",{"code":350,"status":690,"title":691,"wireTitle":692,"action":693,"description":694,"fix":695,"retryable":443,"retry":615},409,"Hay que volver a sincronizar","Resync required","resync","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.","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.",{"code":362,"status":690,"title":697,"wireTitle":698,"action":699,"description":700,"fix":701,"retryable":447,"retry":702},"Los datos del equipo aún se están preparando","Team data is still being prepared","wait_capture","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.","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.","later",{"code":353,"status":704,"title":705,"wireTitle":706,"action":693,"description":707,"fix":708,"retryable":443,"retry":615},410,"Cursor de sincronización caducado","Sync cursor expired","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ó).","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.",{"code":377,"status":710,"title":711,"wireTitle":712,"action":713,"description":714,"fix":715,"retryable":447,"retry":716},429,"Límite de frecuencia superado","Rate limited","retry_after","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.","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.","after",{"code":391,"status":710,"title":718,"wireTitle":719,"action":713,"description":720,"fix":721,"retryable":447,"retry":716},"Cuota diaria superada","Daily quota exceeded","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 \u002Fv1\u002Fteams`, `GET \u002Fv1\u002Fmembers`, `GET \u002Fv1\u002Fbooking_services` y las actividades de un lead. La cuota se renueva a las 00:00 UTC.","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 \u002Fv1\u002Fleads\u002F{id}`, la búsqueda y `GET \u002Fv1\u002Fme` no cuentan para la cuota y siguen funcionando.",{"code":723,"status":724,"title":725,"wireTitle":726,"action":727,"description":728,"fix":729,"retryable":447,"retry":727},"internal_error",500,"Error interno","Internal error","backoff","Algo ha fallado dentro de Totem al responder a esta petición.","Reintenta con una espera exponencial. Si sigue fallando, escribe a soporte e indica el `Totem-Request-Id`.",{"code":731,"status":732,"title":733,"wireTitle":734,"action":727,"description":735,"fix":736,"retryable":447,"retry":727},"api_disabled",503,"API desactivada","API disabled","Totem ha desactivado temporalmente la API para todas las claves.","Conserva tus datos y tus cursores y reintenta más tarde con una espera exponencial.",{"code":738,"status":732,"title":739,"wireTitle":740,"action":727,"description":741,"fix":742,"retryable":447,"retry":727},"service_unavailable","Servicio no disponible","Service unavailable","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.","Reintenta con una espera exponencial; tus datos y tus cursores siguen siendo válidos.",[608,267,627,279,640,295,299,291,377,723,731,738],"beta",{"type":746,"title":679,"status":677,"code":320,"request_id":747,"doc_url":746},"https:\u002F\u002Ftotemstudio.ai\u002Fdevelopers\u002Ferrors#resource_missing","req_0f6b2c1e-8d4a-4b7e-9c3f-5a2d1e7b9c40","guide",[750,751,752],{"id":18,"text":19,"depth":439},{"id":226,"text":227,"depth":439},{"id":423,"text":424,"depth":439},{"path":501,"title":502,"section":451},{"path":401,"title":402,"section":451},[],1792502790372]