# Error Handling

### Error Response Format

All errors follow a consistent format:

**Status Code:** 4xx or 5xx

**Response Body:**
```json
{
  "message": "Human-readable error message",
  "type": "error_type",
  "code": "ERROR_CODE"
}
```

**Example: Authentication Error**
```json
{
  "message": "Partner authentication required",
  "type": "unauthorized",
  "code": "UNAUTHORIZED"
}
```

**Example: Validation Error**
```json
{
  "message": "Invalid brand data: name is required",
  "type": "invalid_data",
  "code": "INVALID_DATA"
}
```

**Example: Not Found Error**
```json
{
  "message": "Partner not found",
  "type": "not_found",
  "code": "NOT_FOUND"
}
```

---

### Common HTTP Status Codes

| Code | Name | Description | Example |
|------|------|-------------|---------|
| **200** | OK | Request succeeded | GET resource |
| **201** | Created | Resource created successfully | POST brand |
| **400** | Bad Request | Invalid request data | Missing required field |
| **401** | Unauthorized | Authentication required or failed | Missing or invalid token |
| **403** | Forbidden | Authenticated but not authorized | Admin-only endpoint with partner token |
| **404** | Not Found | Resource doesn't exist | GET /brands/invalid_id |
| **422** | Unprocessable Entity | Validation error | Invalid email format |
| **500** | Internal Server Error | Server error | Database connection failed |
| **503** | Service Unavailable | Service temporarily down | External API timeout |

---

### Error Types

Error responses follow a consistent JSON shape: a human-readable `message`, and where applicable a `type` code you can branch on programmatically.

**1. Unauthorized (401)**

Returned when authentication is missing or invalid.

```json
{
  "message": "Partner authentication required",
  "type": "unauthorized"
}
```

**2. Not Found (404)**

Returned when the requested resource does not exist.

```json
{
  "message": "Partner not found",
  "type": "not_found"
}
```

**3. Invalid Data (400)**

Returned when the request body or parameters fail validation.

```json
{
  "message": "CustomerLabs not configured properly",
  "type": "invalid_data"
}
```

**4. Generic Error (400)**

Some endpoints return an `error` field with additional detail instead of a `type` code.

```json
{
  "message": "Failed to create brand",
  "error": "Slug already exists"
}
```

---