Errors

The Orga Node SDK defines structured error classes to make exception handling and logging simple and predictable.
All errors extend the base OrgaAIError class, giving you consistent behavior across all Orga SDKs.

Overview

Common sources of errors in the Node SDK include:

Missing or invalid API keys
Temporary server outages or 5xx responses from Orga Cloud
Network or timeout failures
Invalid configuration (e.g., missing userEmail)

The SDK surfaces these issues as typed exceptions you can catch in your code.

Base Class: `OrgaAIError`

The root error type for all SDK exceptions.


import { OrgaAIError } from "@orga-ai/node";
 
try {
  throw new OrgaAIError("Something went wrong");
} catch (err) {
  console.error(err.name); // "OrgaAIError"
  console.error(err.message); // "Something went wrong"
}

Property	Type	Description
`name`	`"OrgaAIError"`	Class identifier.
`message`	`string`	Human‑readable description.
`code?`	`number`	Optional HTTP status code when available.
`type?`	`OrgaAIErrorType`	Optional category label for analytics/logging.

`OrgaAIAuthenticationError`

Represents authentication or credential‑related failures.


import { OrgaAI, OrgaAIAuthenticationError } from "@orga-ai/node";
 
const orga = new OrgaAI({
  apiKey: "sk_orga_ai_invalid",
  userEmail: "user@example.com",
});
 
try {
  await orga.getSessionConfig();
} catch (error) {
  if (error instanceof OrgaAIAuthenticationError) {
    console.error("Authentication failed:", error.message);
  }
}

Property	Type	Description
`name`	`"OrgaAIAuthenticationError"`	Distinguishes credential issues from others.
`message`	`string`	Typically `"Invalid API key or user email"`.
`status?`	`401` \| `403`	HTTP status code if present in response.

`OrgaAIServerError`

Thrown when Orga Cloud responds with an upstream error or when a network failure occurs after retries.


import { OrgaAI, OrgaAIServerError } from "@orga-ai/node";
 
try {
  const creds = await orga.getSessionConfig();
} catch (err) {
  if (err instanceof OrgaAIServerError) {
    console.error("Server error:", err.message);
  }
}

Property	Type	Description
`name`	`"OrgaAIServerError"`	Indicates remote Orga Cloud or network error.
`message`	`string`	Contextual information (`"Failed to fetch ICE servers..."`).
`status?`	`number`	Corresponding HTTP status code (e.g., 500, 504).

Error Type Hierarchy


OrgaAIError
├── OrgaAIAuthenticationError  (invalid credentials, 401/403)
└── OrgaAIServerError          (network/server failure, 5xx)

The hierarchy ensures that all caught errors are instances of OrgaAIError,
allowing broad or specific handling patterns.

Handling Recommendations

Scenario	Recommended Handling
Invalid API key / email	Catch `OrgaAIAuthenticationError` → regenerate credentials or notify devops.
Temporary network failure	Catch `OrgaAIServerError` → retry after a short delay.
Configuration mistake	Catch `OrgaAIError` → review constructor parameters.
Generic fallback	Always include an error logger in production.

Example pattern:


try {
  const session = await orga.getSessionConfig();
  console.log("Session ready:", session);
} catch (error) {
  if (error instanceof OrgaAIAuthenticationError) {
    // Invalid API key or email
    console.error("Check your credentials");
  } else if (error instanceof OrgaAIServerError) {
    // Temporary issue with Orga Cloud
    console.error("Orga Cloud appears unavailable:", error.message);
  } else if (error instanceof OrgaAIError) {
    console.error("SDK misconfiguration:", error.message);
  } else {
    console.error("Unknown error:", error);
  }
}

Logging and Debugging

Enable verbose debug output in the SDK to inspect request flow:


const orga = new OrgaAI({
  apiKey: process.env.ORGA_API_KEY!,
  userEmail: process.env.USER_EMAIL!,
  debug: true,
});
 
await orga.getSessionConfig();

Example output:


[OrgaAI] Fetching session config...
[OrgaAI] Fetched ephemeral token: eyJhbGc...
[OrgaAI] Fetched ICE servers: 3

Common Error Scenarios

Error Example	Root Cause	Resolution
`OrgaAIAuthenticationError: Invalid API key or user email`	API key is invalid or disabled.	Verify credentials in your Orga Dashboard.
`OrgaAIServerError: Failed to fetch ICE servers`	Orga API unreachable or token expired.	Retry; tokens expire quickly.
`FetchError: Request timeout`	Network latency exceeded timeout value.	Increase `timeout` in `OrgaAIConfig`.
`OrgaAIError: User email is required`	Missing `userEmail`.	Add to config (temporary requirement).

Next Steps

Types → Explore available configuration and response types.
Classes → Learn how to use OrgaAI in your backend routes.
Troubleshooting → Troubleshooting guide.