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

# Error Handling

> Understand Carbn API error codes, responses, and handling

## Error Response Structure

All API errors follow a consistent JSON structure with detailed information to help you debug issues. Here is a sample error response:

<CodeGroup>
  ```json Error Response Structure theme={null}
  {
      "code": "4300",
      "httpMethod": "PATCH", 
      "message": "Insufficient permissions to access resource",
      "path": "/onboarding/api/v1/users/all",
      "requestId": "46a7ad4b-c315-441c-ad2c-473f4075e1b5",
      "resourcePath": "/onboarding/api/v1/{proxy+}"
  }
  ```
</CodeGroup>

#### Response Fields

<Accordion title="Field Definitions" icon="list" defaultOpen>
  | Field              | Type     | Description                                  | Example                                  |
  | :----------------- | :------- | :------------------------------------------- | :--------------------------------------- |
  | **`code`**         | `string` | 🏷️ Internal error code for categorization   | `"4300"`, `"4030"`                       |
  | **`httpMethod`**   | `string` | 🌐 HTTP method used in the request           | `"GET"`, `"POST"`, `"PATCH"`             |
  | **`message`**      | `string` | 💬 Human-readable error description          | `"Missing authentication token"`         |
  | **`path`**         | `string` | 🛣️ Exact API endpoint path that was called  | `"/onboarding/api/v1/users/all"`         |
  | **`requestId`**    | `string` | 🔍 Unique identifier for this request (UUID) | `"46a7ad4b-c315-441c-ad2c-473f4075e1b5"` |
  | **`resourcePath`** | `string` | ⚙️ AWS API Gateway resource path pattern     | `"/onboarding/api/v1/{proxy+}"`          |

  <Note>
    **Pro Tip:** The `requestId` is your golden ticket for support - it's like a fingerprint for your specific API call!
  </Note>
</Accordion>

<Info>
  Always include the `requestId` when contacting support - it helps us quickly locate your specific request in our logs.
</Info>

<Warning>
  The `code` field is our internal error classification system. Use this along with the HTTP status code to programmatically handle different error scenarios.
</Warning>

***

## Quick Reference

<Columns cols={2}>
  <Card title="Most Common" icon="circle-alert" color="#07BEB8">
    **Missing API Key (4030)**

    Add `X-API-Key` header to your request
  </Card>

  <Card title="Format Issue" icon="key" color="#FF6B6B">
    **Invalid Format (4100)**

    API key must be exactly 32 alphanumeric characters
  </Card>
</Columns>

<Columns cols={2}>
  <Card title="Not Found" icon="search" color="#FFA500">
    **API Key Not Found (4101)**

    Double-check your API key is correct
  </Card>

  <Card title="Permissions" icon="shield" color="#9966CC">
    **Insufficient Permissions (4300)**

    Contact support for permission updates
  </Card>
</Columns>

***

## Complete Error Reference

### Authentication Errors

<AccordionGroup>
  <Accordion title="[4030] - Missing API Key" icon="key" defaultOpen>
    | Response Field  | Details                                       |
    | :-------------- | :-------------------------------------------- |
    | **HTTP Status** | `403 Forbidden`                               |
    | **Message**     | Missing authentication token                  |
    | **Root Cause**  | No `X-API-Key` header provided in the request |
    | **Impact**      | 🔴 High - Blocks all API access               |
    | **Fix Time**    | ⚡ \< 1 minute                                 |

    <Note>
      Add the `X-API-Key` header with your API key to all requests.
    </Note>

    <CodeGroup>
      ```bash cURL theme={null}
      curl -H "X-API-Key: <api-key>" \
           -H "Content-Type: application/json" \
           https://api.carbnconnect.com/onboarding/api/v1/users/all
      ```

      ```javascript JavaScript theme={null}
      const response = await fetch('https://api.carbnconnect.com/onboarding/api/v1/users/all', {
        headers: {
          'Content-Type': 'application/json',
          'X-API-Key': '<api-key>'
        }
      });
      ```

      ```python Python theme={null}
      import requests

      headers = {
          'Content-Type': 'application/json',
          'X-API-Key': '<api-key>'
      }

      response = requests.get(
          'https://api.carbnconnect.com/onboarding/api/v1/users/all',
          headers=headers
      )
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="[4100] - Invalid API Key Format" icon="triangle-alert">
    | Response Field  | Details                                           |
    | :-------------- | :------------------------------------------------ |
    | **HTTP Status** | `403 Forbidden`                                   |
    | **Message**     | Invalid API key format                            |
    | **Root Cause**  | API key is not exactly 32 alphanumeric characters |
    | **Impact**      | 🔴 High - Authentication fails                    |
    | **Fix Time**    | ⚡ \< 30 seconds                                   |

    <Warning>
      Verify API Key format requirements - API keys are case-sensitive and must be exactly 32 characters long (A-Z, a-z, 0-9)
    </Warning>
  </Accordion>

  <Accordion title="[4101] - API Key Not Found" icon="search">
    | Response Field  | Details                             |
    | :-------------- | :---------------------------------- |
    | **HTTP Status** | `401 Unauthorized`                  |
    | **Message**     | API key not found                   |
    | **Root Cause**  | API key doesn't exist in our system |
    | **Impact**      | 🔴 High - Complete access denial    |
    | **Fix Time**    | ⏱️ 2-3 minutes                      |

    <Callout icon="key" color="#FFC107" iconType="regular">
      Verify your API key is correct or generate a new API key from the [dashboard](https://dashboard.carbnconnect.com).
    </Callout>
  </Accordion>

  <Accordion title="[4102] - API Key Expired" icon="clock">
    | Response Field  | Details                                |
    | :-------------- | :------------------------------------- |
    | **HTTP Status** | `401 Unauthorized`                     |
    | **Message**     | API key has expired                    |
    | **Root Cause**  | API key has passed its expiration date |
    | **Impact**      | 🔴 High - All requests blocked         |
    | **Fix Time**    | ⏱️ 2-3 minutes                         |

    <Note>
      Generate a new API key from your [dashboard](https://dashboard.carbnconnect.com).
    </Note>

    <Info>
      **Pro Tip:** Set up API key rotation reminders to avoid service interruptions
    </Info>
  </Accordion>

  <Accordion title="[4103] - API Key Inactive" icon="ban">
    | Response Field  | Details                                   |
    | :-------------- | :---------------------------------------- |
    | **HTTP Status** | `401 Unauthorized`                        |
    | **Message**     | API key is inactive                       |
    | **Root Cause**  | API key has been suspended or deactivated |
    | **Impact**      | 🔴 High - Account-level issue             |
    | **Fix Time**    | ⏰ 1-24 hours (support dependent)          |

    <Danger>
      **Account Issue:** This usually indicates a billing or compliance concern. Contact [support](mailto:support@carbn.xyz) immediately.
    </Danger>
  </Accordion>
</AccordionGroup>

### Authorization Errors

<AccordionGroup>
  <Accordion title="[4300] - Insufficient Permissions" icon="shield-alert" defaultOpen>
    | Response Field  | Details                                                       |
    | :-------------- | :------------------------------------------------------------ |
    | **HTTP Status** | `403 Forbidden`                                               |
    | **Message**     | Insufficient permissions to access resource                   |
    | **Root Cause**  | Your API key lacks the required permissions for this endpoint |
    | **Impact**      | 🟡 Medium - Specific endpoints blocked                        |
    | **Fix Time**    | ⏰ 2-24 hours (support dependent)                              |

    <Note>
      **Permission Levels:** Different endpoints require different permission levels. Check the specific endpoint documentation for required permissions.
    </Note>

    <Info>
      **Common Cause:** This often happens when using a read-only API key for write operations (POST, PATCH, DELETE)
    </Info>
  </Accordion>
</AccordionGroup>

***

## HTTP Status Code Reference

<AccordionGroup>
  <Accordion title="Success Codes (2xx)" icon="circle-check-big" defaultOpen>
    | Status Code | Status Name | Description                             | Action Required    |
    | :---------- | :---------- | :-------------------------------------- | :----------------- |
    | **`200`**   | **OK**      | Your request has completed successfully | No action required |
    | **`201`**   | **Created** | Resource created successfully           | No action required |

    <Check>
      **2xx responses** indicate successful requests. Your API call worked as expected and you can proceed with the response data.
    </Check>
  </Accordion>

  <Accordion title="Client Error Codes (4xx)" icon="triangle-alert">
    | Status Code | Status Name      | Description                                  | Action Required    |
    | :---------- | :--------------- | :------------------------------------------- | :----------------- |
    | **`400`**   | **Bad Request**  | Request format is invalid or malformed       | Fix request syntax |
    | **`401`**   | **Unauthorized** | Authentication failed or missing credentials | Check API key      |
    | **`403`**   | **Forbidden**    | Access forbidden due to permissions          | Check permissions  |
    | **`404`**   | **Not Found**    | Resource doesn't exist or not found          | Verify resource ID |
    | **`429`**   | **Rate Limited** | Too many requests sent recently              | Wait and retry     |

    <Warning>
      **4xx errors** mean there's an issue with your request. Double-check your API key, request format, and permissions.
    </Warning>
  </Accordion>

  <Accordion title="Server Error Codes (5xx)" icon="server-crash">
    | Status Code | Status Name             | Description                     | Action Required          |
    | :---------- | :---------------------- | :------------------------------ | :----------------------- |
    | **`500`**   | **Internal Error**      | Something went wrong on our end | Contact support          |
    | **`502`**   | **Bad Gateway**         | Gateway/proxy error             | Retry or contact support |
    | **`503`**   | **Service Unavailable** | Temporary service issue         | Wait and retry           |

    <Danger>
      **5xx errors** are on us! If you see these consistently, please contact support with your `requestId`.
    </Danger>
  </Accordion>
</AccordionGroup>

***

## Getting Help

<Columns cols={1}>
  <Card title="Contact Support" icon="headset" href="mailto:support@carbn.xyz" arrow="true">
    When contacting support, please include:
    <Check>**Request ID** from the error response</Check>
    <Check>**Endpoint** you were trying to access</Check>
    <Check>**Error** response details available</Check>
    <Check>**Timestamp** when the error occurred</Check>
  </Card>
</Columns>