Errors
Every failure the SDK raises subclasses ConvilynError — catch the base class for a single safety net, or branch on code / statusCode for a specific failure mode.
Hierarchy
| Class | Extends | Meaning |
|---|---|---|
ConvilynError | Error | Base — everything the SDK raises |
AuthError | ConvilynError | No / malformed API key |
APIError | ConvilynError | HTTP 4xx / 5xx from the Convilyn API |
RateLimitError | APIError | Rate limited |
PlanRequiredError | APIError | Plan does not include this action |
QuotaExceededError | APIError | Quota / cost cap reached |
S3UploadError | APIError | Presigned upload step returned non-success |
RetryExhaustedError | APIError | Retry policy ran out of attempts |
JobFailedError | ConvilynError | Conversion job reached status failed |
JobTimeoutError | ConvilynError | Conversion polling exceeded its timeout |
GoalJobFailedError | ConvilynError | Goal workflow reached status failed |
GoalJobTimeoutError | ConvilynError | Goal-workflow polling exceeded its timeout |
WebSocketError | ConvilynError | Workflow event stream could not proceed |
Handling
Branch on the specific subclass when you want a tailored remedy; fall back to ConvilynError for everything else.
import {
ConvilynError,
QuotaExceededError,
RateLimitError,
PlanRequiredError,
} from "@convilyn/sdk";
try {
await client.goals.run({ goalText: "…", files: [file.fileId] });
} catch (err) {
if (err instanceof QuotaExceededError) {
console.error(
`Need ${err.costCredits} credits, have ${err.balanceCredits}. Top up: ${err.topUpUrl}`,
);
} else if (err instanceof PlanRequiredError) {
console.error(`Upgrade required: ${err.upgradeUrl}`);
} else if (err instanceof RateLimitError) {
console.error("Rate limited — back off and retry.");
} else if (err instanceof ConvilynError) {
console.error("SDK error:", err.message);
} else {
throw err;
}
}