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

# Error Handling

> Understanding API error responses

## Error format

The API uses [RFC 7807 Problem Details](https://datatracker.ietf.org/doc/html/rfc7807) format for all error responses:

```json theme={null}
{
  "type": "https://api.rawugc.com/errors/insufficient_credits",
  "title": "Insufficient Credits",
  "status": 402,
  "detail": "Insufficient credits. Required: 6, Available: 2",
  "instance": "/api/v1/videos/generate/req_abc123"
}
```

| Field      | Description                                          |
| ---------- | ---------------------------------------------------- |
| `type`     | URI identifying the error type                       |
| `title`    | Human-readable summary                               |
| `status`   | HTTP status code                                     |
| `detail`   | Specific explanation for this occurrence             |
| `instance` | URI identifying this specific request                |
| `errors`   | Field-specific validation errors (for 400 responses) |

## Validation errors

When request validation fails, the response includes field-specific errors:

```json theme={null}
{
  "type": "https://api.rawugc.com/errors/validation_error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": {
    "prompt": ["Required"],
    "model": ["Invalid enum value"]
  }
}
```

## HTTP status codes

| Status | Meaning               | Common Causes                                               |
| ------ | --------------------- | ----------------------------------------------------------- |
| `400`  | Bad Request           | Invalid parameters, malformed JSON, missing required fields |
| `401`  | Unauthorized          | Missing or invalid API key, expired key                     |
| `402`  | Payment Required      | Insufficient credits for the requested operation            |
| `404`  | Not Found             | Resource doesn't exist or doesn't belong to you             |
| `429`  | Too Many Requests     | Rate limit exceeded (see [Rate Limits](/rate-limits))       |
| `500`  | Internal Server Error | Unexpected server error                                     |

## Error types

| Error Type               | Status | Description                             |
| ------------------------ | ------ | --------------------------------------- |
| `authentication_error`   | 401    | General authentication failure          |
| `empty_api_key`          | 401    | Authorization header present but empty  |
| `invalid_api_key`        | 401    | API key is invalid or revoked           |
| `missing_authentication` | 401    | No authentication credentials provided  |
| `verification_failed`    | 401    | API key verification failed             |
| `insufficient_scope`     | 403    | API key lacks required permissions      |
| `validation_error`       | 400    | Request body validation failed          |
| `insufficient_credits`   | 402    | Not enough credits for the operation    |
| `rate_limit_exceeded`    | 429    | Too many requests in the current window |
| `not_found`              | 404    | Requested resource not found            |
| `internal_error`         | 500    | Unexpected server error                 |

## Handling errors

We recommend implementing retry logic with exponential backoff for `429` and `500` errors:

```javascript theme={null}
async function apiRequest(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) return response.json();

    if (response.status === 429 || response.status >= 500) {
      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    // Non-retryable error
    const error = await response.json();
    throw new Error(`${error.title}: ${error.detail}`);
  }

  throw new Error('Max retries exceeded');
}
```