Troubleshooting

Most issues with the Node SDK arise from incorrect environment variables, invalid API keys, or network configuration.
Use this checklist to quickly identify and resolve problems.

Missing or Invalid API Key

Error message:

Error: API key is required

or

OrgaAIAuthenticationError: Invalid API key or user email

Cause:
The apiKey property wasn’t provided during initialization, or it’s malformed or expired.

Fix:

1. Verify your API key is set in your environment.
2. Check that your SDK initialization includes it:

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

3. Confirm the key matches the one created in your Orga Dashboard .

Invalid or Missing Email

Error message:

Error: User email is required

or

OrgaAIError: Invalid email format

Cause:
The userEmail is currently a required field for authentication.

Fix:

• Ensure USER_EMAIL is set and formatted correctly (e.g., you@example.com):

  USER_EMAIL=you@example.com

💡 Heads up:
The email requirement will be removed in an upcoming release.

401 Unauthorized or 403 Forbidden

Error message:

OrgaAIServerError: Failed to fetch ephemeral token: Unauthorized

Cause:
Your API key is invalid, disabled, or missing sufficient permissions.

Fix:

• Re‑generate your API key from your Orga Dashboard .
• Double‑check that your backend is sending:

  Authorization: Bearer sk_orga_ai_************

• Verify the endpoint:

  https://api.orga-ai.com/v1/realtime/client-secrets

Network or Timeout Errors

Error message:

FetchError: network timeout at: https://api.orga-ai.com/v1/realtime/client-secrets

Cause:
Outbound HTTPS requests to Orga’s API are blocked, timing out, or the default timeout (10 seconds) is too short for your environment.

Fix:

1. Ensure your server allows outbound HTTPS connections to https://api.orga-ai.com.
2. Increase the timeout in the SDK constructor:

   const orga = new OrgaAI({
     apiKey: process.env.ORGA_API_KEY!,
     userEmail: process.env.USER_EMAIL!,
     timeout: 20000, // 20 seconds
   });

3. Retry or log failed attempts with debug: true enabled.

Debug Mode

Use verbose logging to trace all HTTP operations:

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

Console output example:

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

🧠 Tip: Enable debug logs only in non‑production environments.

Internal Server Error (500)

Error message:

Failed to get session config: Internal error

Cause:
The SDK encountered an unexpected response or unhandled exception from Orga Cloud.

Fix:

• Wrap your API route in a try/catch block to handle internal errors gracefully:

try {
	  const creds = await orga.getSessionConfig();
	  res.json(creds);
	} catch (err) {
	  console.error("Orga error:", err);
	  res.status(500).json({ error: "Internal server error" });
	}

• Retry after a few seconds—errors can occur if the backend rate‑limits your region.

Still stuck?

• Revisit the Quick Start to verify setup order.
• Enable debug: true in new OrgaAI({debug: true}) to inspect connection logs.
• Report bugs in the Orga AI GitHub repo .