The Avala SDK throws specific error classes to help you handle different types of failures. All error classes extend the base AvalaError class.
Error hierarchy
AvalaError
├── AuthenticationError
├── NotFoundError
├── RateLimitError
├── ValidationError
└── ServerError
AvalaError
Base error class for all Avala SDK errors.
Error message describing what went wrong.
statusCode
number | undefined
required
HTTP status code associated with the error, if applicable.
Raw response body from the API, if available.
Example
try {
const dataset = await avala.datasets.get("dataset-uid");
} catch (error) {
if (error instanceof AvalaError) {
console.error(`Error ${error.statusCode}: ${error.message}`);
console.error("Response body:", error.body);
}
}
AuthenticationError
Thrown when authentication fails (HTTP 401).
Error message describing the authentication failure.
Always set to 401 for authentication errors.
Raw response body from the API.
Common causes
- Missing or invalid API key
- Expired API key
- Incorrect authentication credentials
Example
import { Avala, AuthenticationError } from "@avala-ai/sdk";
const avala = new Avala({ apiKey: "invalid-key" });
try {
const datasets = await avala.datasets.list();
} catch (error) {
if (error instanceof AuthenticationError) {
console.error("Authentication failed. Please check your API key.");
}
}
NotFoundError
Thrown when a requested resource is not found (HTTP 404).
Error message indicating the resource was not found.
Always set to 404 for not found errors.
Raw response body from the API.
Common causes
- Invalid resource UID
- Resource has been deleted
- No access to the resource
Example
import { Avala, NotFoundError } from "@avala-ai/sdk";
const avala = new Avala({ apiKey: process.env.AVALA_API_KEY });
try {
const dataset = await avala.datasets.get("non-existent-uid");
} catch (error) {
if (error instanceof NotFoundError) {
console.error("Dataset not found. Please check the UID.");
}
}
RateLimitError
Thrown when the rate limit is exceeded (HTTP 429).
Error message indicating the rate limit was exceeded.
Always set to 429 for rate limit errors.
Raw response body from the API.
Number of seconds to wait before retrying, or null if not provided by the API.
Example
import { Avala, RateLimitError } from "@avala-ai/sdk";
const avala = new Avala({ apiKey: process.env.AVALA_API_KEY });
try {
const datasets = await avala.datasets.list();
} catch (error) {
if (error instanceof RateLimitError) {
const retryAfter = error.retryAfter ?? 60;
console.error(`Rate limit exceeded. Retry after ${retryAfter} seconds.`);
// Wait and retry
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
const datasets = await avala.datasets.list();
}
}
ValidationError
Thrown when request validation fails (HTTP 400 or similar).
Error message describing the validation failure.
HTTP status code (typically 400, but can be other 4xx codes).
Raw response body from the API.
Array of detailed validation errors, if provided by the API.
Common causes
- Missing required fields
- Invalid field values
- Invalid request parameters
- Constraint violations
Example
import { Avala, ValidationError } from "@avala-ai/sdk";
const avala = new Avala({ apiKey: process.env.AVALA_API_KEY });
try {
const webhook = await avala.webhooks.create({
targetUrl: "invalid-url", // Invalid URL format
events: [],
});
} catch (error) {
if (error instanceof ValidationError) {
console.error("Validation failed:", error.message);
console.error("Details:", error.details);
}
}
ServerError
Thrown when a server-side error occurs (HTTP 5xx).
Error message describing the server error.
HTTP status code (5xx range).
Raw response body from the API.
Common causes
- Internal server errors
- Service unavailable
- Gateway timeouts
- Database errors
Example
import { Avala, ServerError } from "@avala-ai/sdk";
const avala = new Avala({ apiKey: process.env.AVALA_API_KEY });
try {
const dataset = await avala.datasets.get("dataset-uid");
} catch (error) {
if (error instanceof ServerError) {
console.error(`Server error (${error.statusCode}): ${error.message}`);
console.error("Please try again later or contact support.");
}
}
Best practices
Handle specific error types
Always check for specific error types to provide appropriate error handling:
try {
const result = await avala.someOperation();
} catch (error) {
if (error instanceof AuthenticationError) {
// Refresh credentials or prompt for login
} else if (error instanceof RateLimitError) {
// Implement backoff and retry
} else if (error instanceof ValidationError) {
// Show validation errors to user
} else if (error instanceof NotFoundError) {
// Handle missing resource
} else if (error instanceof ServerError) {
// Log and report to monitoring
} else {
// Handle unexpected errors
}
}
Implement retry logic
For transient errors like rate limits and server errors:
async function withRetry<T>(
operation: () => Promise<T>,
maxRetries = 3
): Promise<T> {
let lastError: Error;
for (let i = 0; i < maxRetries; i++) {
try {
return await operation();
} catch (error) {
lastError = error;
if (error instanceof RateLimitError) {
const delay = (error.retryAfter ?? Math.pow(2, i)) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
} else if (error instanceof ServerError) {
const delay = Math.pow(2, i) * 1000;
await new Promise(resolve => setTimeout(resolve, delay));
} else {
throw error; // Don't retry other errors
}
}
}
throw lastError;
}
// Usage
const datasets = await withRetry(() => avala.datasets.list());
Log error details
Always log the full error context for debugging:
try {
const result = await avala.someOperation();
} catch (error) {
if (error instanceof AvalaError) {
console.error({
message: error.message,
statusCode: error.statusCode,
body: error.body,
stack: error.stack,
});
}
throw error;
}