> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Seguridad y errores

> Protege las credenciales de socio, aísla a los clientes y gestiona los fallos del SDK

## Proteger las claves de socio

Las claves de socio autorizan operaciones a nivel de proyecto. Guárdalas en un gestor de secretos
del lado del servidor o en una variable de entorno cifrada, e inyéctalas solo en procesos de backend
de confianza.

> [!WARNING]
>
> Nunca envíes una clave de socio a tu frontend como configuración, respuesta de API, parámetro de
> consulta o variable de entorno renderizada. Tu backend debe exponer endpoints acotados que autoricen al cliente
> con sesión iniciada antes de llamar a Social media studio.

Usa claves `pk_test_` durante el desarrollo y claves `pk_live_` solo en producción.
Mantén separados los proyectos de prueba y de producción, rota las claves periódicamente y revoca una clave
de inmediato si pudo haberse expuesto.

## Autorizar cada operación de cliente

El SDK autentica a tu aplicación, no al cliente que usa tu producto.
Antes de cada llamada al SDK:

1. Autentica al cliente en tu aplicación.
2. Resuelve en tu servidor el `endUserId` de Social media studio almacenado para ese cliente.
3. Verifica que los ID de conexión y de publicación solicitados pertenecen a ese cliente.
4. Llama al SDK con esos ID resueltos en el servidor.

Nunca aceptes un `endUserId` arbitrario desde un navegador ni lo pases sin
comprobar la propiedad en tu base de datos.

## Ámbitos de las claves

Las claves de socio pueden restringirse a las capacidades que necesita un servicio:

| Recurso | Ámbito de lectura | Ámbito de escritura |
| - | - | - |
| Usuarios finales | `end_users:read` | `end_users:write` |
| Conexiones | `connections:read` | `connections:write` |
| Sesiones de conexión | `connect_sessions:read` | `connect_sessions:write` |
| Publicaciones | `posts:read` | `posts:write` |
| Multimedia | — | `media:write` |
| Webhooks | `webhooks:read` | `webhooks:write` |

Siempre que sea posible, usa claves distintas y con los mínimos privilegios para servicios independientes.

## Gestionar los errores del SDK

Toda solicitud de API fallida lanza `SoMePlatformError`:

```ts theme={null}
import {
  SoMePlatformError,
  SoMePlatformClient,
} from "@social-media-scheduler/sdk";

try {
  await soMe.posts.get(endUserId, postId);
} catch (error) {
  if (error instanceof SoMePlatformError) {
    logger.error("Social media studio request failed", {
      status: error.status,
      details: error.details,
    });
  }
  throw error;
}
```

| Estado | Significado | Gestión recomendada |
| - | - | - |
| `0` | Error de red, fallo de DNS o tiempo de espera agotado | Reintenta con espera creciente cuando sea seguro |
| `400` | Entrada no válida, plataforma que no coincide o URL de retorno no permitida | Corrige la solicitud; no la reintentes sin cambios |
| `401` | Clave de socio ausente, no válida, caducada o revocada | Detente y rota o sustituye la clave |
| `403` | La clave carece de un ámbito necesario | Usa una clave con los ámbitos correctos |
| `404` | El recurso no existe en este proyecto o usuario final | Concilia los ID almacenados |
| `409` | El espacio de trabajo del cliente no está listo | Reintenta tras resolver el estado indicado |
| `429` | Se alcanzó el límite de solicitudes | Respeta la indicación de reintento y usa espera exponencial |
| `5xx` | Fallo temporal del servicio de Social media studio | Reintenta con espera exponencial acotada |

En la creación de publicaciones, los reintentos son seguros solo si reutilizas la misma clave de
idempotencia. No reintentes a ciegas otras operaciones de escritura a menos que tu aplicación pueda
confirmar su resultado.

## Registro

Registra el contexto de la solicitud, como el ID de tu cliente, el ID del usuario final, la operación, el estado
HTTP y la clave de idempotencia. No registres claves de socio completas, secretos de webhook,
tokens de OAuth, URL de subida prefirmadas ni metadatos sensibles de clientes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.