# Error Handling & Status Codes

The Cineamo API uses standard HTTP status codes to indicate the success or failure of requests.

## 📊 HTTP Status Codes

### ✅ Success Codes (2xx)

- `200 OK` - Request succeeded
- `201 Created` - Resource successfully created
- `204 No Content` - Request succeeded with no response body

### ❌ Client Error Codes (4xx)

- `400 Bad Request` - Invalid request parameters
- `401 Unauthorized` - Missing or invalid authentication
- `403 Forbidden` - Insufficient permissions
- `404 Not Found` - Resource doesn't exist
- `422 Unprocessable Entity` - Validation errors
- `429 Too Many Requests` - Rate limit exceeded

### 🔥 Server Error Codes (5xx)

- `500 Internal Server Error` - Server-side error
- `502 Bad Gateway` - Gateway error
- `503 Service Unavailable` - Service temporarily unavailable

## Error Response Format

All error responses follow this JSON structure:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "request_id": "req_abc123"
  }
}
```

### Error Response Fields

- `code` - Machine-readable error code
- `message` - Human-readable error message
- `details` - Additional error details (optional)
- `request_id` - Unique request identifier for support

## Common Error Codes

| Code | Description |
|------|-------------|
| `AUTHENTICATION_REQUIRED` | Missing authentication credentials |
| `INVALID_TOKEN` | Invalid or expired access token |
| `INSUFFICIENT_PERMISSIONS` | User lacks required permissions |
| `RESOURCE_NOT_FOUND` | Requested resource doesn't exist |
| `VALIDATION_ERROR` | Request validation failed |
| `RATE_LIMIT_EXCEEDED` | Too many requests |
| `INTERNAL_ERROR` | Server-side error |

## Handling Errors

### Retry Strategy

For `5xx` errors and `429` rate limit errors:

1. Wait before retrying (use exponential backoff)
2. Maximum 3 retry attempts
3. Include `request_id` when contacting support

### Example Error Handling

```javascript
async function makeApiRequest(url) {
  try {
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });

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

    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    // Handle error appropriately
  }
}
```

## Getting Help

If you encounter persistent errors, contact support with:
- The `request_id` from the error response
- The endpoint and HTTP method used
- Request timestamp
- Error message and code