Every failed request throws a SocifyrError, which carries the HTTP status code and the human-readable error message from the API.

SocifyrError

import { SocifyrError } from '@socifyr/sdk'

try {
  await socifyr.uploads.text({
    connections: ['nonexistent-slug'],
    text: 'hi',
  })
} catch (err) {
  if (err instanceof SocifyrError) {
    console.log(err.status)  // 400
    console.log(err.message) // 'Connection "nonexistent-slug" not found'
    console.log(err.body)    // full API response object
  }
}

Common status codes

Status	Meaning	What to do
400	Bad request — invalid params, missing fields, validation errors	Fix the request payload
401	Bad / missing API key	Check apiKey and workspaceId
403	API key valid but lacks permission for this workspace / action	Check the key's workspace and role
404	Resource doesn't exist	Verify the ID
409	Conflict — e.g. trying to publish an already-published post	Often safe to ignore
422	Platform rejected the content (caption too long, image too small)	Read err.message for the specific reason
429	Rate limited	SDK retries automatically; if you still hit this, slow down
5xx	Server-side failure	SDK retries; if persistent, contact support

Validation errors

The API returns validation errors as a string array. The SDK joins them into one message:

// Backend response:
//   { success: false, error: ["text must be a string", "connections should not be empty"] }
// SDK throws:
//   SocifyrError { message: "text must be a string, connections should not be empty" }

Network errors

Transient failures (DNS errors, timeouts, 5xx) are retried up to maxRetries times. After exhausting retries, the SDK throws a SocifyrError with status: 0 and a message like "Network error: ...".

Pattern: graceful fallback

async function postSafely(params: UploadTextParams): Promise<Upload | null> {
  try {
    return await socifyr.uploads.text(params)
  } catch (err) {
    if (err instanceof SocifyrError) {
      if (err.status === 429) {
        console.warn('Rate limited, will retry later')
        return null
      }
      if (err.status >= 400 && err.status < 500) {
        console.error('Client error — not retrying:', err.message)
        return null
      }
    }
    throw err // unknown error — let it bubble
  }
}

Patterns: matching on message

The error messages are stable enough to match on:

catch (err) {
  if (err instanceof SocifyrError && err.message.includes('Token has expired')) {
    // Surface to the user — they need to reconnect this platform
  }
}