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?
| Class | HTTP status | code | Extra fields |
|---|---|---|---|
ValidationError | 400 | validation_error | errors: Record<string, string[]> |
AuthenticationError | 401 | authentication_error | |
UsageLimitError | 402 (the API sends plan limits as 403, so they arrive as PermissionError) | usage_limit | |
PermissionError | 403 | permission_error | |
NotFoundError | 404 | not_found | |
RateLimitError | 429 | rate_limit | retryAfter: number (seconds) |
SocifyrError | any other (409, 422, 5xx) | api_error | |
SocifyrError | 408 | timeout | request aborted after timeout |
SocifyrError | 0 | network_error | no 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.
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?
| Status | Typical cause | Fix |
|---|---|---|
| 400 | Bad payload, unknown connection slug, platform rejected the content | Fix the request. Read message |
| 401 | Bad or missing API key | Check apiKey |
| 402 | Not sent for plan limits today (UsageLimitError is reserved for it) | |
| 403 | Plan limit reached (posts, scheduled posts, X allowance, accounts, storage, API keys, seats), or the key or member role lacks the permission | Read message; for plan limits check workspaces.usage() |
| 404 | ID or slug does not exist in this workspace | Verify the ID, and that you use the key for the workspace that owns it |
| 409 | State conflict, for example publishing something already published | Often safe to ignore |
| 429 | Rate limited | Wait retryAfter seconds |
| 5xx | Server error | Safe methods are retried; for writes, check state then retry |
How do I back off on a rate limit?
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:
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.