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

# Error Handling

> We use the conventional HTTP response codes to indicate the success or failure of an API request.

<Info>
  Codes in the 2xx range indicate success. Codes in the 4xx range indicate an
  error that failed given the information provided (e.g., a required parameter
  was omitted, etc.). Codes in the 5xx range indicate an error with our
  servers.
</Info>

## HTTP Status Codes

<AccordionGroup>
  <Accordion title="2xx Success Codes">
    | Status Code | Description                                 |
    | ----------- | ------------------------------------------- |
    | 200         | OK - Request was successful                 |
    | 201         | Created - Resource was successfully created |
  </Accordion>

  <Accordion title="4xx Client Error Codes">
    | Status Code | Description                                                                           |
    | ----------- | ------------------------------------------------------------------------------------- |
    | 400         | Bad Request - The request was unacceptable, often due to missing a required parameter |
    | 401         | Unauthorized - No valid API key was provided                                          |
    | 402         | Request Failed - The parameters were valid but the request failed                     |
    | 403         | Forbidden - The API key doesn't have permission to perform the request                |
    | 404         | Not Found - The requested resource doesn't exist                                      |
    | 429         | Too Many Requests - Too many requests hit the API                                     |
  </Accordion>

  <Accordion title="5xx Server Error Codes">
    | Status Code | Description                                                         |
    | ----------- | ------------------------------------------------------------------- |
    | 500         | Internal Server Error - Something went wrong on Carbon's end        |
    | 502         | Bad Gateway - Invalid response from an upstream server              |
    | 503         | Service Unavailable - Carbon is temporarily offline for maintenance |
    | 504         | Gateway Timeout - The server didn't respond in time                 |
  </Accordion>
</AccordionGroup>

## Error Response Format

All errors return JSON in the following format:

```json theme={null}
{
  "status": "error",
  "message": "A descriptive error message",
  "data": {
    "error_code": "SPECIFIC_ERROR_CODE",
    "details": "Additional error details if available"
  }
}
```

## Common Error Examples

<CodeGroup>
  ```json Authentication Error (401) theme={null}
  {
    "status": "error",
    "message": "Unauthorized access",
    "data": {
      "error_code": "INVALID_API_KEY",
      "details": "The provided API key is invalid or expired"
    }
  }
  ```

  ```json Validation Error (400) theme={null}
  {
    "status": "error",
    "message": "Validation failed",
    "data": {
      "error_code": "MISSING_REQUIRED_FIELD",
      "details": "The 'customer_id' field is required"
    }
  }
  ```

  ```json Rate Limit Error (429) theme={null}
  {
    "status": "error",
    "message": "Rate limit exceeded",
    "data": {
      "error_code": "RATE_LIMIT_EXCEEDED",
      "details": "You have exceeded the rate limit. Please wait before making another request."
    }
  }
  ```
</CodeGroup>

## Best Practices

<Warning>
  **Always Handle Errors Gracefully**

  Implement proper error handling in your application to ensure a good user experience when API calls fail.
</Warning>

<Tip>
  **Retry Logic**

  For 5xx errors, implement exponential backoff retry logic as these are typically temporary issues.
</Tip>

<Note>
  **Log Error Details**

  Always log the full error response for debugging purposes, but never expose sensitive error details to end users.
</Note>