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

# Error Codes

> API error reference

## Error Codes

The DomShot API uses standard HTTP status codes and returns structured error objects.

## Error response format

All errors return a JSON object with the following structure:

```json theme={null}
{
  "error": "error_code",
  "errorDescription": "Human-readable error message"
}
```

| Field              | Type   | Description                  |
| ------------------ | ------ | ---------------------------- |
| `error`            | string | Machine-readable error code  |
| `errorDescription` | string | Human-readable error message |

## Error codes

### 401 Unauthorized

#### invalid\_token

Invalid or expired API key.

```json theme={null}
{
  "error": "invalid_token",
  "errorDescription": "The API key is invalid or expired"
}
```

**Solution**: Check your API key in the [Dashboard](https://domshot.dev/dashboard).

#### inactive\_subscription

No active subscription found.

```json theme={null}
{
  "error": "inactive_subscription",
  "errorDescription": "No active subscription found"
}
```

**Solution**: Ensure you have an active subscription.

### 402 Payment Required

#### insufficient\_balance

Free tier balance exhausted.

```json theme={null}
{
  "error": "insufficient_balance",
  "errorDescription": "Free tier balance exhausted. Please upgrade your plan."
}
```

**Solution**: Upgrade to a paid plan to continue using the service.

### 429 Rate Limit Exceeded

#### rate\_limit\_exceeded

Too many requests within the rate limit window.

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "errorDescription": "Rate limit exceeded. Try again at 2024-01-01T12:00:00.000Z",
  "retryAfter": 30
}
```

**Solution**: Wait for the number of seconds specified in `retryAfter` or upgrade your plan for higher limits.

### 500 Internal Server Error

#### screenshot\_failed

Screenshot generation failed.

```json theme={null}
{
  "error": "screenshot_failed",
  "errorDescription": "Failed to load the target URL"
}
```

**Causes**:

* Target URL is unreachable
* Page timeout
* Invalid URL
* Internal server error

**Solution**: Verify the target URL is accessible, try increasing the timeout parameter, or contact support if the issue persists.

## Status code reference

| Code | Error                  | Description                           |
| ---- | ---------------------- | ------------------------------------- |
| 200  | -                      | Success                               |
| 401  | invalid\_token         | Invalid or expired API key            |
| 401  | inactive\_subscription | No active subscription                |
| 402  | insufficient\_balance  | Free tier balance exhausted           |
| 422  | -                      | Validation error (invalid parameters) |
| 429  | rate\_limit\_exceeded  | Rate limit exceeded                   |
| 500  | screenshot\_failed     | Screenshot generation failed          |

## Rate limit headers

All responses include rate limit information:

| Header                  | Description                               |
| ----------------------- | ----------------------------------------- |
| `X-RateLimit-Limit`     | Requests per minute allowed for your plan |
| `X-RateLimit-Remaining` | Requests remaining in current window      |
| `X-RateLimit-Reset`     | ISO timestamp when window resets          |

## Troubleshooting

| Issue                  | Solution                         |
| ---------------------- | -------------------------------- |
| Invalid API key        | Regenerate in dashboard          |
| No active subscription | Subscribe to a plan              |
| Rate limit exceeded    | Wait or upgrade plan             |
| Timeout error          | Increase timeout parameter       |
| Screenshot blank       | Check target URL loads correctly |
| Credits exhausted      | Upgrade to paid plan             |