Troubleshooting

This guide covers common issues you may encounter when working with the LegionEdge Platform and how to resolve them.

Authentication Errors

401 Unauthorized: "authentication_failed"

Cause: The API key or access token is invalid, expired, or revoked.

Solution:

1. Verify the key is correct and has not been revoked in the dashboard.
2. Check that you are using the right key for the environment (live vs. test).
3. For OAuth tokens, check if the token has expired and refresh it.

import { AuthenticationError } from "@legionedge/sdk";

try {
  await client.auth.whoami();
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("API key is invalid. Generate a new one in the dashboard.");
  }
}

403 Forbidden: "insufficient_permissions"

Cause: The authenticated user or API key lacks the required permissions.

Solution:

1. Check the scopes on your API key: client.apiKeys.get(keyId).
2. Verify your role in the organization or project.
3. Ask an organization admin to grant the necessary permissions.

API Errors

429 Too Many Requests

Cause: You have exceeded the rate limit for your plan.

Solution:

• Check the Retry-After header and wait before retrying.
• Enable automatic retries in the SDK:

const client = new LegionEdge({
  apiKey: process.env.LEGIONEDGE_API_KEY!,
  retries: { maxRetries: 3 },
  rateLimiting: { enabled: true, strategy: "adaptive" },
});

• Consider upgrading your plan if you consistently hit limits.

422 Validation Error

Cause: The request body contains invalid data.

Solution: Check the error response for field-level details:

try {
  await client.projects.create({ name: "" });
} catch (err) {
  if (err instanceof LegionEdgeError && err.code === "validation_error") {
    // err.details contains field-level errors
    for (const field of err.details) {
      console.error(`${field.path}: ${field.message}`);
    }
  }
}

500 Internal Server Error

Cause: An unexpected error on the platform side.

Solution:

1. Retry the request. The SDK retries 500-series errors automatically if retries are enabled.
2. If the error persists, check the status page for ongoing incidents.
3. Contact support with the requestId from the error response.

Deployment Failures

Deployment Stuck in "building" Status

Possible causes:

• Build dependencies are failing to install.
• The build script is hanging.

Solution:

1. Check the deployment logs:

const logs = await client.deployments.getLogs("deploy_abc123");
console.log(logs);

2. Verify your build command works locally.
3. Check for missing environment variables or secrets.

Deployment Fails on Health Check

Cause: The application is not responding on the configured health check path.

Solution:

1. Ensure your application exposes the health check endpoint (default: /health).
2. Verify the health check configuration:

const deployment = await client.deployments.get("deploy_abc123");
console.log("Health check config:", deployment.healthCheck);

3. Check application logs for startup errors.

SDK Issues

"Module not found" After Installation

Solution: Ensure you are using a supported Node.js version (18+) and your tsconfig.json has the correct moduleResolution setting:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

TypeScript Type Errors

Solution: Ensure you are using TypeScript 5.0+ and have installed the latest SDK version:

npm update @legionedge/sdk

Performance Issues

Slow API Responses

1. Enable SDK-level caching for read-heavy workloads.
2. Use field selection to reduce payload sizes.
3. Check your network latency to api.legionedge.com.

curl -w "Connect: %{time_connect}s\nTotal: %{time_total}s\n" -o /dev/null -s \
  https://api.legionedge.com/v2/health

Next Steps

• Browse the FAQ for answers to common questions.
• Contact support for issues not covered here.