> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qumo-deploy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling & Types

> Handling APIError, HTTP status codes, and inspecting exported TypeScript types.

# Error Handling & Types

## Handling `APIError`

All non-2xx responses produced by the Qumo control plane throw an instance of `APIError`.

```typescript theme={null}
import { APIError, QumoClient } from "@qumo-deploy/sdk";

const client = new QumoClient({
  baseUrl: "https://api.qumo.dev",
  apiKey: "invalid_key",
});

try {
  await client.projects.list();
} catch (err: unknown) {
  if (err instanceof APIError) {
    console.error(`HTTP Status: ${err.status}`);
    console.error(`Server Message: ${err.message}`);
    console.error(`Error Payload:`, err.data);

    switch (err.status) {
      case 401:
        console.error("Authentication failed: verify QUMO_API_KEY or Bearer token.");
        break;
      case 403:
        console.error("Access forbidden: check your IAM roles and workspace permissions.");
        break;
      case 404:
        console.error("Requested resource not found.");
        break;
      case 429:
        console.error("Rate limit exceeded: implement exponential backoff.");
        break;
      default:
        console.error("Unexpected error occurred.");
    }
  } else {
    throw err;
  }
}
```

***

## IAM Role Identifiers

When working with permissions and bindings, always import and use the canonical `IAM_ROLE_IDS` constants rather than hardcoded strings:

```typescript theme={null}
import { IAM_ROLE_IDS, type IAMRoleID } from "@qumo-deploy/sdk";

// Built-in IAM roles:
// - "roles/platform.admin"
// - "roles/project.viewer"
// - "roles/project.editor"
// - "roles/project.admin"
// - "roles/tenant.admin"

function isTenantAdmin(role: IAMRoleID): boolean {
  return role === "roles/tenant.admin";
}
```

***

## Exported Type Interfaces

The SDK exports canonical types for all control plane entities:

| Type               | Description                                                             |
| :----------------- | :---------------------------------------------------------------------- |
| `User`             | Authenticated user profile (`id`, `email`, `name`, `github_login`).     |
| `Session`          | Active session metadata, active tenant, and IAM role.                   |
| `Tenant`           | Tenant / organization entity (`id`, `name`, `billing_email`).           |
| `Project`          | Project unit (`id`, `name`, `tenant_id`, `environment`).                |
| `IssuedCredential` | Minted relay JWT credentials, expiration, and assigned relay endpoints. |
| `APIKey`           | Scoped API key metadata (`id`, `name`, `prefix`, `created_at`).         |
| `Bot`              | Machine identity credentials (`id`, `name`, `tenant_id`).               |
| `AuditEvent`       | Append-only audit trail event.                                          |