> ## 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.

# Security and Errors

> Protect partner credentials, isolate customers, and handle SDK failures

## Protect partner keys

Partner keys authorize project-wide operations. Store them in a server-side
secret manager or encrypted environment variable and inject them only into
trusted backend processes.

<Warning>
  Never send a partner key to your frontend as configuration, an API response, a
  query parameter, or a rendered environment variable. Your backend should expose
  narrow endpoints that authorize the signed-in customer before calling Social media studio.
</Warning>

Use `pk_test_` keys while developing and `pk_live_` keys only in production.
Keep test and live projects separate, rotate keys periodically, and revoke a key
immediately if it may have been exposed.

## Authorize every customer operation

The SDK authenticates your application, not the customer using your product.
Before every SDK call:

1. Authenticate the customer in your application.
2. Resolve the customer's stored Social media studio `endUserId` on your server.
3. Verify that requested connection and post IDs belong to that customer.
4. Call the SDK using those server-resolved IDs.

Never accept an arbitrary `endUserId` from a browser and pass it through without
checking ownership in your database.

## Key scopes

Partner keys can be restricted to the capabilities a service needs:

| Resource         | Read scope              | Write scope              |
| ---------------- | ----------------------- | ------------------------ |
| End users        | `end_users:read`        | `end_users:write`        |
| Connections      | `connections:read`      | `connections:write`      |
| Connect sessions | `connect_sessions:read` | `connect_sessions:write` |
| Posts            | `posts:read`            | `posts:write`            |
| Media            | —                       | `media:write`            |
| Webhooks         | `webhooks:read`         | `webhooks:write`         |

Use separate, least-privilege keys for independent services where possible.

## Handle SDK errors

Every unsuccessful API request throws `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;
}
```

| Status | Meaning                                                    | Recommended handling                               |
| ------ | ---------------------------------------------------------- | -------------------------------------------------- |
| `0`    | Network error, DNS failure, or request timeout             | Retry with backoff when safe                       |
| `400`  | Invalid input, platform mismatch, or disallowed return URL | Fix the request; do not retry unchanged            |
| `401`  | Missing, invalid, expired, or revoked partner key          | Stop and rotate or replace the key                 |
| `403`  | The key lacks a required scope                             | Use a correctly scoped key                         |
| `404`  | Resource does not exist in this project/end user           | Reconcile stored IDs                               |
| `409`  | Customer workspace is not ready                            | Retry after resolving the reported state           |
| `429`  | Rate limit reached                                         | Respect retry guidance and use exponential backoff |
| `5xx`  | Temporary Social media studio service failure              | Retry with capped exponential backoff              |

For post creation, retries are safe only when you reuse the same idempotency
key. Do not blindly retry other write operations unless your application can
confirm their outcome.

## Logging

Log request context such as your customer ID, end-user ID, operation, HTTP
status, and idempotency key. Do not log full partner keys, webhook secrets,
OAuth tokens, presigned upload URLs, or sensitive customer metadata.