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

# Errors and Debugging

> API error types, HTTP status codes, and retry strategies

All API errors follow a consistent JSON format:

```json theme={"dark"}
{
  "error": {
    "type": "error_type",
    "code": "http_status_code",
    "message": "Human-readable error message"
  }
}
```

## Error Types

| HTTP Code | Error Type | Description |
| - | - | - |
| 400 | `invalid_request_error` | Request body or parameters are malformed |
| 401 | `authentication_error` | API key is missing, invalid, or expired |
| 402 | `insufficient_balance` | Account balance is insufficient |
| 403 | `permission_error` | Account lacks access rights to the resource |
| 404 | `not_found_error` | Model or resource does not exist |
| 405 | `invalid_request_error` | Wrong HTTP method |
| 429 | `rate_limit_error` | Too many requests, please retry later |
| 500+ | `api_error` | An error occurred while processing your request |
| 529 | `overloaded_error` | Service is temporarily overloaded, please retry later |

## Error Examples

### Authentication Error (401)

```json theme={"dark"}
{
  "error": {
    "type": "authentication_error",
    "code": "401",
    "message": "Incorrect API key provided. Please visit https://console.pipellm.ai/account/api-keys to find your API key."
  }
}
```

### Rate Limit Error (429)

When you exceed rate limits, the response includes your current limits:

```json theme={"dark"}
{
  "error": {
    "type": "rate_limit_error",
    "code": "429",
    "message": "Rate limit exceeded. Your current limit is 120 requests per minute (approximately 2.00 requests per second). Please visit https://console.pipellm.ai/billing to upgrade your plan for higher limits.",
    "rate_limit": {
      "rpm": 120,
      "qps": 2.00
    }
  }
}
```

### Insufficient Balance (402)

```json theme={"dark"}
{
  "error": {
    "type": "insufficient_balance",
    "code": "402",
    "message": "Insufficient balance. Please recharge your account at https://console.pipellm.ai/billing."
  }
}
```

### Internal Error (500)

```json theme={"dark"}
{
  "error": {
    "type": "api_error",
    "code": "500",
    "message": "Internal server error occurred. Our team has been notified and is working on it."
  }
}
```

## Model-Specific Errors

### Model Not Found

Unknown model IDs return `400`. List current IDs with [`GET /v1/models`](/api-reference/list-models).

```json theme={"dark"}
{
  "error": {
    "type": "invalid_request_error",
    "code": "400",
    "message": "not-a-model is not a valid model ID. You can view all the models in our documentation: https://docs.pipellm.ai"
  }
}
```

### Model Missing in Request

```json theme={"dark"}
{
  "error": {
    "type": "invalid_request_error",
    "code": "400",
    "message": "The 'model' field is required but was not provided in the request"
  }
}
```

## Retry

`429` and `529` are retryable. Back off and retry; `402` and `401` are not. Rate-limit windows are in the `x-ratelimit-*` response headers. See [Rate Limits](/api-reference/rate-limits).

## Support

<Columns cols={2}>
  <Card title="Contact Support" icon="envelope" href="mailto:support@pipellm.ai">
    Email us for assistance with API issues.
  </Card>

  <Card title="Usage Dashboard" icon="chart-line" href="https://console.pipellm.ai">
    Monitor your API usage and manage your account.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.