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

# Error Handling

> Handle API errors gracefully with structured error responses.

## Overview

Factify uses conventional HTTP status codes and returns structured error responses.

## Error Response Format

All errors follow a consistent JSON structure:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "Name cannot be empty",
    "param": "name",
    "code": "missing_required_field"
  }
}
```

| Field     | Type           | Description                              |
| --------- | -------------- | ---------------------------------------- |
| `type`    | string         | Error category for broad handling        |
| `code`    | string         | Specific error for programmatic handling |
| `message` | string         | Human-readable explanation               |
| `param`   | string \| null | Field that caused the error              |

## Error Types

| Type                    | HTTP Status | When                                 |
| ----------------------- | ----------- | ------------------------------------ |
| `invalid_request_error` | 400         | Validation failed, malformed request |
| `authentication_error`  | 401         | Missing or invalid API key           |
| `authorization_error`   | 403         | Valid key, insufficient permissions  |
| `not_found_error`       | 404         | Resource doesn't exist               |
| `rate_limit_error`      | 429         | Too many requests                    |
| `api_error`             | 500+        | Server-side failure                  |

## SDK Error Classes

[`FactifyError`](https://github.com/factify-inc/factify-typescript/blob/main/src/models/errors/factifyerror.ts) is the base class for all HTTP error responses:

| Property                  | Type       | Description                |
| ------------------------- | ---------- | -------------------------- |
| `error.message`           | `string`   | Error message              |
| `error.httpMeta.response` | `Response` | HTTP response with headers |
| `error.httpMeta.request`  | `Request`  | HTTP request details       |
| `error.data$`             | varies     | Structured error data      |

## Handling Errors

```typescript theme={null}
import { Factify } from "@factify/sdk";
import * as errors from "@factify/sdk/models/errors";

const factify = new Factify({
  bearerAuth: process.env.FACTIFY_KEY,
});

async function run() {
  try {
    const result = await factify.apiKeys.list();
    console.log(result);
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof errors.FactifyError) {
      console.log(error.message);
      console.log(error.httpMeta.response.status);
      console.log(error.httpMeta.response.headers);
      console.log(error.httpMeta.request);

      // Handle specific error types
      if (error instanceof errors.ErrorT) {
        console.log(error.data$.error);
      }
    }
  }
}

run();
```

## Network Errors

The SDK provides specific error classes for network issues:

| Error Class               | Description                            |
| ------------------------- | -------------------------------------- |
| `ConnectionError`         | Unable to connect to server            |
| `RequestTimeoutError`     | Request timed out                      |
| `RequestAbortedError`     | Request was aborted                    |
| `InvalidRequestError`     | Invalid request input                  |
| `ResponseValidationError` | Response doesn't match expected schema |

## Error Codes Reference

<Tabs>
  <Tab title="Validation Errors">
    | Code                     | Description                  |
    | ------------------------ | ---------------------------- |
    | `missing_required_field` | Required field not provided  |
    | `invalid_field_value`    | Field value fails validation |
    | `invalid_enum_value`     | Value not in allowed set     |
    | `invalid_file_type`      | Uploaded file not PDF        |
    | `file_too_large`         | File exceeds size limit      |
    | `invalid_page_token`     | Pagination token invalid     |
  </Tab>

  <Tab title="Authentication Errors">
    | Code              | Description                   |
    | ----------------- | ----------------------------- |
    | `missing_api_key` | No Authorization header       |
    | `invalid_api_key` | Key format invalid or revoked |
    | `expired_api_key` | Key has expired               |
  </Tab>

  <Tab title="Authorization Errors">
    | Code                       | Description              |
    | -------------------------- | ------------------------ |
    | `insufficient_permissions` | Key lacks required scope |
  </Tab>

  <Tab title="Other Errors">
    | Code                  | Description               |
    | --------------------- | ------------------------- |
    | `resource_not_found`  | Resource ID doesn't exist |
    | `rate_limit_exceeded` | Request quota exhausted   |
    | `internal_error`      | Unexpected server error   |
  </Tab>
</Tabs>