Error Handling

Handle API errors with typed exceptions and built-in retry logic in the Platform SDK.

The Platform SDK provides typed error classes for every HTTP error category. All errors extend AmigoError, which includes the HTTP status code and a descriptive message.

Error Types

import { errors } from '@amigo-ai/platform-sdk'

// Available error classes:
errors.AmigoError           // Base error class, all SDK errors extend this
errors.AuthenticationError  // 401, invalid or expired API key
errors.NotFoundError        // 404, resource does not exist
errors.BadRequestError      // 400, invalid request format or parameters
errors.ValidationError      // 422, request validation failed
errors.ConflictError        // 409, resource conflict (for example, duplicate name)
errors.NetworkError         // Connection issues, timeouts

Every error exposes:

Property	Type	Description
message	string	Human-readable error message
status	number | undefined	HTTP status code (undefined for network errors)
cause	unknown	Underlying cause for network errors

Basic Error Handling

import { AmigoClient, errors } from '@amigo-ai/platform-sdk'

const client = new AmigoClient({
  apiKey: process.env.AMIGO_API_KEY!,
  workspaceId: process.env.AMIGO_WORKSPACE_ID!,
})

async function fetchAgent(agentId: string) {
  try {
    const agent = await client.agents.get(agentId)
    console.log(`Agent: ${agent.name}`)

  } catch (error) {
    if (error instanceof errors.AuthenticationError) {
      console.error('Authentication failed. Check your API key.')

    } else if (error instanceof errors.NotFoundError) {
      console.error(`Agent ${agentId} does not exist`)

    } else if (error instanceof errors.BadRequestError) {
      console.error(`Invalid request: ${error.message}`)

    } else if (error instanceof errors.ValidationError) {
      console.error(`Validation failed: ${error.message}`)

    } else if (error instanceof errors.ConflictError) {
      console.error(`Conflict: ${error.message}`)

    } else if (error instanceof errors.NetworkError) {
      console.error(`Network error: ${error.message}`)
      // The SDK retries automatically. If this throws, retries are exhausted.

    } else if (error instanceof errors.AmigoError) {
      console.error(`API error (${error.status}): ${error.message}`)

    } else {
      console.error('Unexpected error:', error)
    }
  }
}

Common Error Scenarios

Authentication Errors

AuthenticationError (HTTP 401) is thrown when the API key is invalid or has expired.

try {
  await client.agents.list()
} catch (error) {
  if (error instanceof errors.AuthenticationError) {
    // Regenerate the API key in the Amigo dashboard
    console.error('API key is invalid or expired')
  }
}

Not Found Errors

NotFoundError (HTTP 404) is thrown when a resource ID does not exist in the workspace.

try {
  const agent = await client.agents.get('non-existent-id')
} catch (error) {
  if (error instanceof errors.NotFoundError) {
    // Fall back to a default agent or return null
    console.error('Agent not found. It may have been deleted.')
  }
}

Conflict Errors

ConflictError (HTTP 409) commonly occurs when creating a resource with a name that already exists. These are often recoverable.

try {
  await client.agents.create({ name: 'My Agent', description: '' })
} catch (error) {
  if (error instanceof errors.ConflictError) {
    // Try a different name or fetch the existing resource
    console.error('An agent with this name already exists')
  }
}

Validation Errors

ValidationError (HTTP 422) indicates the request body failed server-side validation. Check the error message for field-level details.

try {
  await client.agents.create({ name: '', description: '' }) // empty name
} catch (error) {
  if (error instanceof errors.ValidationError) {
    console.error(`Validation failed: ${error.message}`)
  }
}

Built-in Retry Logic

The SDK automatically retries failed requests for transient failures:

Error Type	Retry Strategy
Network errors	Automatic exponential backoff
Rate limiting (429)	Automatic retry with proper delay
Server errors (5xx)	Intelligent retry with backoff

Automatic Retries. You don't need to implement retry logic manually. The SDK handles retries for you. If a NetworkError reaches your catch block, all retry attempts have been exhausted.

Best Practices

1. Catch specific error types. Handle NotFoundError differently from AuthenticationError.

2. Log with context. Include the resource ID and operation in error logs.

3. Treat ConflictError as recoverable. It often means the resource already exists, so you can fetch it instead.

4. Trust built-in retries. Only add custom retry logic for business-level failures, not HTTP errors.

5. Validate locally first. Use TypeScript types to catch missing required fields before they become ValidationErrors at runtime.

Next Steps

• Quickstart. First API calls with proper error handling.

• Agents. Agent management reference.

• Analytics & Observability. Usage monitoring.