warmbly/docs/content/docs/reference/error-codes.mdx

---
title: Error Codes
description: Reference for all API error codes and their meanings.
---

# Error Codes

The Warmbly API uses standard HTTP status codes and returns structured error responses in JSON format.

## Error Response Format

All errors follow this structure:

```json
{
  "error": "Error Type",
  "message": "Human-readable description of what went wrong."
}
```

## HTTP Status Codes

### Client Errors (4xx)

| Code | Error | Description |
|------|-------|-------------|
| 400 | Bad Request | Invalid request syntax or parameters |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Authenticated but lacks permission |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Resource already exists |
| 422 | Unprocessable | Validation failed |

### Server Errors (5xx)

| Code | Error | Description |
|------|-------|-------------|
| 500 | Internal Server Error | Unexpected server error |
| 501 | Not Implemented | Feature not available |
| 503 | Service Unavailable | Service temporarily down |

## Error Details

### 400 Bad Request

Returned when the request cannot be processed due to invalid syntax.

**Common causes:**
- Invalid JSON in request body
- Missing required fields
- Invalid field types
- Values outside allowed ranges

**Example:**

```json
{
  "error": "Bad Request",
  "message": "invalid request body"
}
```

**How to fix:**
- Check that your JSON is valid
- Verify all required fields are present
- Ensure field values match expected types

### 401 Unauthorized

Returned when authentication fails.

**Common causes:**
- Missing `Authorization` header
- Invalid API key format
- Expired API key
- Revoked API key

**Example:**

```json
{
  "error": "Unauthorized",
  "message": "Token not found."
}
```

**How to fix:**
- Include the `Authorization: Bearer wmbly_...` header
- Verify your API key is correct
- Check if your key has expired or been revoked
- Generate a new key if necessary

### 403 Forbidden

Returned when authenticated but lacking necessary permissions.

**Common causes:**
- API key lacks required permission
- Request IP not in allowlist
- Email account not in allowlist
- Organization access restricted

**Example:**

```json
{
  "error": "Forbidden",
  "message": "You doesn't have access to this feature."
}
```

**How to fix:**
- Check your API key's permissions
- Verify IP restrictions if configured
- Request additional permissions if needed

### 404 Not Found

Returned when the requested resource doesn't exist.

**Common causes:**
- Invalid resource ID
- Resource was deleted
- Resource belongs to different organization
- Typo in endpoint URL

**Example:**

```json
{
  "error": "Not Found",
  "message": "Resource not found."
}
```

**How to fix:**
- Verify the resource ID is correct
- Check that the resource hasn't been deleted
- Ensure you're using the correct endpoint

### 409 Conflict

Returned when the request conflicts with existing data.

**Common causes:**
- Trying to create a resource that already exists
- Duplicate unique values

**Example:**

```json
{
  "error": "Conflict",
  "message": "resource already exists"
}
```

### 422 Unprocessable

Returned when validation fails on the request data.

**Common causes:**
- Invalid email format
- String exceeds maximum length
- Number outside valid range
- Invalid enum value

**Example:**

```json
{
  "error": "Unprocessable",
  "message": "validation failed"
}
```

### 500 Internal Server Error

Returned when an unexpected error occurs on the server.

**Example:**

```json
{
  "error": "Internal Server Error",
  "message": "Something went wrong."
}
```

**How to fix:**
- Retry the request after a short delay
- If persistent, contact support with request details

### 503 Service Unavailable

Returned when the service is temporarily unavailable.

**Example:**

```json
{
  "error": "Service Unavailable",
  "message": "service unavailable"
}
```

**How to fix:**
- Wait and retry with exponential backoff
- Check status page for incidents

## Error Handling Best Practices

### Implement Retry Logic

For transient errors (5xx, 429), implement exponential backoff:

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

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

      // Don't retry client errors (4xx) except rate limits
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error(`Client error: ${response.status}`);
      }

      // Retry server errors and rate limits
      if (attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}
```

### Parse Error Responses

Always parse and handle error responses:

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

  if (!response.ok) {
    const error = await response.json();
    throw new ApiError(response.status, error.error, error.message);
  }

  return response.json();
}

class ApiError extends Error {
  constructor(status, type, message) {
    super(message);
    this.status = status;
    this.type = type;
  }
}
```

## Rate Limiting

When you exceed rate limits, you'll receive:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

```json
{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 60 seconds."
}
```

Use the `Retry-After` header to determine when to retry.

## See Also

- [Authentication](/authentication)
- [API Keys Overview](/api-keys)