Skip to content

TypeScript SDK errors ​

Every failed request throws a SocifyrError or one of its subclasses. Check with instanceof, then read status, code and message.

Which error classes does the SDK throw? ​

ClassHTTP statuscodeExtra fields
ValidationError400validation_errorerrors: Record<string, string[]>
AuthenticationError401authentication_error
UsageLimitError402 (the API sends plan limits as 403, so they arrive as PermissionError)usage_limit
PermissionError403permission_error
NotFoundError404not_found
RateLimitError429rate_limitretryAfter: number (seconds)
SocifyrErrorany other (409, 422, 5xx)api_error
SocifyrError408timeoutrequest aborted after timeout
SocifyrError0network_errorno response received

All subclasses extend SocifyrError, which has status, code, message and an optional requestId. The HTTP layer does not currently fill requestId from the response, so do not rely on it.

typescript
import {
  SocifyrError,
  ValidationError,
  RateLimitError,
  PermissionError,
} from '@socifyr/sdk'

try {
  await socifyr.uploads.text({ connections: ['nonexistent-slug'], text: 'hi' })
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.status, err.message) // 400 Connection "nonexistent-slug" not found
  } else if (err instanceof RateLimitError) {
    console.log(`retry in ${err.retryAfter}s`)
  } else if (err instanceof PermissionError) {
    // 403: a plan limit (posts, X allowance, accounts...) or a role/guardrail block
    console.log('blocked:', err.message)
  } else if (err instanceof SocifyrError) {
    console.log(err.status, err.code, err.message)
  } else {
    throw err
  }
}

The message comes from the error field of the API's error envelope (see error handling guide). When the API returns an array of validation messages, the message is whatever the server sent in error. The per-field errors map on ValidationError is only filled if the response body carries an errors object.

What do the common statuses mean? ​

StatusTypical causeFix
400Bad payload, unknown connection slug, platform rejected the contentFix the request. Read message
401Bad or missing API keyCheck apiKey
402Not sent for plan limits today (UsageLimitError is reserved for it)
403Plan limit reached (posts, scheduled posts, X allowance, accounts, storage, API keys, seats), or the key or member role lacks the permissionRead message; for plan limits check workspaces.usage()
404ID or slug does not exist in this workspaceVerify the ID, and that you use the key for the workspace that owns it
409State conflict, for example publishing something already publishedOften safe to ignore
429Rate limitedWait retryAfter seconds
5xxServer errorSafe methods are retried; for writes, check state then retry

How do I back off on a rate limit? ​

typescript
import { RateLimitError } from '@socifyr/sdk'

async function withRateLimit<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
  for (let i = 0; ; i++) {
    try {
      return await fn()
    } catch (err) {
      if (err instanceof RateLimitError && i < attempts - 1) {
        await new Promise((r) => setTimeout(r, err.retryAfter * 1000))
        continue
      }
      throw err
    }
  }
}

await withRateLimit(() => socifyr.uploads.text({ connections: ['x-myhandle'], text: 'Hi' }))

How do I tell a failed platform from a failed request? ​

A request error means Socifyr rejected the call. A platform failure happens later, per channel, after the API accepted the post. Read it from status, not from a thrown error:

typescript
const status = await socifyr.uploads.getStatus(ack.requestId!)
for (const ch of status.channels) {
  if (ch.result?.status === 'failed') console.log(ch.platform, ch.result.error)
}

uploads.waitForCompletion() throws a plain Error (not a SocifyrError) if the post does not reach completed, failed or partial_failure before its timeout.

FAQ ​

What happens when a connection token has expired? ​

The post is accepted, then the affected channel fails. The reason appears in result.error from uploads.getStatus(), not as a thrown HTTP error. Refresh or reconnect the account. See connections and connection concepts.

Does the SDK retry on 429? ​

No. Handle RateLimitError yourself, as above.

Next steps ​