elizaos--eliza/packages/docs/cloud/errors.mdx

---
title: Error Handling
description: Understand elizaOS Cloud API errors and how to handle them gracefully in your applications.
---

# Error Handling

Learn how to handle API errors effectively in your elizaOS Cloud integrations.

## Error Format

All errors follow a consistent JSON format:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": "Additional context (optional)",
    "requestId": "req_abc123"
  }
}
```

## HTTP Status Codes

| Status | Meaning             | Action                 |
| ------ | ------------------- | ---------------------- |
| `400`  | Bad Request         | Fix request parameters |
| `401`  | Unauthorized        | Check authentication   |
| `402`  | Payment Required    | Add credits or payment |
| `403`  | Forbidden           | Check permissions      |
| `404`  | Not Found           | Verify resource exists |
| `409`  | Conflict            | Resolve conflict       |
| `422`  | Unprocessable       | Fix validation errors  |
| `429`  | Rate Limited        | Slow down, retry later |
| `500`  | Server Error        | Retry, contact support |
| `503`  | Service Unavailable | Wait, retry later      |

## Error Codes

### Authentication Errors

| Code              | Description              | Solution              |
| ----------------- | ------------------------ | --------------------- |
| `UNAUTHORIZED`    | Invalid/missing auth     | Check API key         |
| `INVALID_API_KEY` | API key not recognized   | Verify key is correct |
| `EXPIRED_TOKEN`   | Session expired          | Re-authenticate       |
| `FORBIDDEN`       | Insufficient permissions | Check key permissions |

### Request Errors

| Code               | Description              | Solution             |
| ------------------ | ------------------------ | -------------------- |
| `INVALID_REQUEST`  | Malformed request        | Check request format |
| `MISSING_FIELD`    | Required field missing   | Add required field   |
| `INVALID_FIELD`    | Field value invalid      | Fix field value      |
| `VALIDATION_ERROR` | Schema validation failed | Check all fields     |

### Resource Errors

| Code             | Description            | Solution              |
| ---------------- | ---------------------- | --------------------- |
| `NOT_FOUND`      | Resource doesn't exist | Verify resource ID    |
| `ALREADY_EXISTS` | Duplicate resource     | Use existing resource |
| `CONFLICT`       | State conflict         | Resolve conflict      |

### Rate Limiting

| Code             | Description         | Solution       |
| ---------------- | ------------------- | -------------- |
| `RATE_LIMITED`   | Too many requests   | Wait and retry |
| `QUOTA_EXCEEDED` | Plan quota exceeded | Upgrade plan   |

### Payment Errors

| Code                   | Description        | Solution             |
| ---------------------- | ------------------ | -------------------- |
| `INSUFFICIENT_CREDITS` | Not enough credits | Top up account       |
| `PAYMENT_REQUIRED`     | Payment needed     | Add payment method   |
| `PAYMENT_FAILED`       | Payment declined   | Check payment method |

### Generation Errors

| Code                | Description              | Solution                   |
| ------------------- | ------------------------ | -------------------------- |
| `CONTENT_POLICY`    | Content policy violation | Modify content             |
| `GENERATION_FAILED` | Generation error         | Retry with different input |
| `MODEL_UNAVAILABLE` | Model offline            | Try different model        |
| `CONTEXT_LENGTH`    | Input too long           | Reduce input size          |

## Handling Errors

### JavaScript Example

```javascript
async function makeRequest(url, options) {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const error = await response.json();

      switch (error.error.code) {
        case "RATE_LIMITED":
          const retryAfter = response.headers.get("Retry-After");
          await sleep(retryAfter * 1000);
          return makeRequest(url, options); // Retry

        case "UNAUTHORIZED":
          throw new AuthError("Invalid API key");

        case "INSUFFICIENT_CREDITS":
          throw new PaymentError("Please top up your account");

        default:
          throw new ApiError(error.error.message, error.error.code);
      }
    }

    return response.json();
  } catch (error) {
    if (error instanceof ApiError) throw error;
    throw new NetworkError("Network request failed");
  }
}
```

### Python Example

```python
import requests
import time

class ElizaAPIError(Exception):
    def __init__(self, code, message):
        self.code = code
        self.message = message

def make_request(url, headers, data=None, retries=3):
    for attempt in range(retries):
        try:
            response = requests.post(url, headers=headers, json=data)

            if response.status_code == 429:
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                continue

            if not response.ok:
                error = response.json()['error']
                raise ElizaAPIError(error['code'], error['message'])

            return response.json()

        except requests.RequestException as e:
            if attempt == retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff
```

## Retry Strategy

### Retryable Errors

These errors can be retried:

- `429` Rate Limited - Wait for `Retry-After`
- `500` Server Error - Exponential backoff
- `503` Service Unavailable - Wait and retry
- `GENERATION_FAILED` - Retry with modifications

### Non-Retryable Errors

Don't retry these:

- `400` Bad Request
- `401` Unauthorized
- `403` Forbidden
- `404` Not Found
- `CONTENT_POLICY`

### Exponential Backoff

```javascript
async function retryWithBackoff(fn, maxRetries = 5) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (!isRetryable(error) || i === maxRetries - 1) {
        throw error;
      }

      const delay = Math.min(1000 * Math.pow(2, i), 30000);
      const jitter = Math.random() * 1000;
      await sleep(delay + jitter);
    }
  }
}
```

## Debugging

### Request ID

Every response includes a request ID:

```
X-Request-Id: req_abc123def456
```

Include this when contacting support.

### Verbose Errors

Enable verbose errors in development:

```bash
curl -X POST "https://elizacloud.ai/api/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Debug: true" \
  -d '...'
```

## Best Practices

- **Handle All Errors** — Never assume requests will succeed
- **Log Errors** — Log error codes and request IDs for debugging
- **User Feedback** — Show meaningful error messages to users
- **Graceful Degradation** — Have fallbacks for critical features

## Troubleshooting

### "UNAUTHORIZED" errors

**Problem**: Getting 401 errors on every request.

**Solutions**:

1. Verify your API key starts with `eliza_`
2. Check the key hasn't been revoked in [Dashboard → API Keys](https://elizacloud.ai/dashboard/api-keys)
3. Ensure you're sending either `Authorization: Bearer YOUR_KEY` or `X-API-Key: YOUR_KEY`

### "RATE_LIMITED" errors

**Problem**: Getting 429 errors during normal usage.

**Solutions**:

1. Implement exponential backoff (see code example above)
2. Check your rate limit headers: `X-RateLimit-Remaining`
3. Upgrade your plan for higher limits at [Dashboard → Billing](https://elizacloud.ai/dashboard/billing)

### "INSUFFICIENT_CREDITS" errors

**Problem**: Getting 402 errors.

**Solutions**:

1. Check your balance at [Dashboard → Billing](https://elizacloud.ai/dashboard/billing)
2. Enable auto top-up to avoid interruptions
3. Top up credits via Stripe or crypto payments

### Streaming not working

**Problem**: Stream responses come as a single chunk.

**Solutions**:

1. Ensure `stream: true` is set in your request body
2. Don't buffer the response—read chunks as they arrive
3. Check your proxy/CDN isn't buffering SSE responses

### Agent not responding as expected

**Problem**: Agent ignores personality/style settings.

**Solutions**:

1. Verify character JSON is valid with the [API Explorer](https://elizacloud.ai/dashboard/api-explorer)
2. Check you're using the agent ID (not model name) as the `model` parameter
3. Clear conversation history and start fresh

## Next Steps

<CardGroup>
  <CardGroup.Card title="Rate Limits" href="/cloud/rate-limits">
    Handle rate limiting
  </CardGroup.Card>
  <CardGroup.Card title="API Reference" href="/cloud/api">
    Complete API documentation
  </CardGroup.Card>
  <CardGroup.Card title="Authentication" href="/cloud/authentication">
    Fix auth errors
  </CardGroup.Card>
</CardGroup>