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

# Error Handling

> Learn how the Management API handles errors, common error codes, error response formats, and best practices for error handling.

## Overview

The Management API uses standard HTTP status codes and returns error responses in a consistent JSON format.

## HTTP Status Codes

| Status Code | Meaning               | Description                              |
| ----------- | --------------------- | ---------------------------------------- |
| 200         | OK                    | Request succeeded                        |
| 201         | Created               | Resource created successfully            |
| 400         | Bad Request           | Invalid request parameters or body       |
| 401         | Unauthorized          | Authentication failed or token invalid   |
| 403         | Forbidden             | Insufficient permissions                 |
| 404         | Not Found             | Resource not found                       |
| 409         | Conflict              | Resource conflict (e.g., duplicate name) |
| 500         | Internal Server Error | Server error                             |

## Error Response Format

All error responses follow this format:

```json theme={null}
{
  "error": "error_code",
  "error_description": "Human-readable error message"
}
```

## Common Error Codes

### 400 Bad Request

#### Error Codes

* `bad_request` - General validation error
* `validation_failed` - Request validation failed
* `invalid_parameter` - Invalid parameter value

#### Example Response

```json theme={null}
{
  "error": "validation_failed",
  "error_description": "Validation failed: name is required"
}
```

#### Common Causes

* Missing required fields
* Invalid field values
* Invalid data types
* Validation rule violations

### 401 Unauthorized

#### Error Codes

* `unauthorized_client` - Invalid credentials
* `invalid_token` - Token is invalid or expired
* `token_expired` - Token has expired

#### Example Response

```json theme={null}
{
  "error": "invalid_token",
  "error_description": "Token is invalid or expired"
}
```

#### Common Causes

* Missing `Authorization` header
* Invalid token format
* Expired token
* Revoked token

### 403 Forbidden

#### Error Codes

* `forbidden` - Insufficient permissions
* `access_denied` - Access denied for this resource

#### Example Response

```json theme={null}
{
  "error": "forbidden",
  "error_description": "You do not have permission to perform this action"
}
```

#### Common Causes

* User lacks required role
* Resource access restrictions
* Project-level permissions

### 404 Not Found

#### Error Codes

* `not_found` - Resource not found
* `resource_not_found` - Specific resource not found

#### Example Response

```json theme={null}
{
  "error": "not_found",
  "error_description": "Project 'MyProject' not found"
}
```

#### Common Causes

* Incorrect resource name
* Resource was deleted
* Wrong project/environment context

### 409 Conflict

#### Error Codes

* `conflict` - Resource conflict
* `duplicate_name` - Name already exists

#### Example Response

```json theme={null}
{
  "error": "duplicate_name",
  "error_description": "API Proxy with name 'MyAPI' already exists"
}
```

#### Common Causes

* Duplicate resource name
* Unique constraint violation

### 500 Internal Server Error

#### Error Codes

* `internal_error` - Internal server error
* `server_error` - Unexpected server error

#### Example Response

```json theme={null}
{
  "error": "internal_error",
  "error_description": "An unexpected error occurred. Please try again later."
}
```

#### Common Causes

* Database errors
* System failures
* Unexpected exceptions

## Error Handling Best Practices

### 1. Check Status Codes

Always check the HTTP status code before processing the response:

```bash theme={null}
# Good
if response.status_code == 200:
    process_success(response.json())
else:
    handle_error(response.json())

# Bad
process_success(response.json())  # May fail on error responses
```

### 2. Parse Error Messages

Extract and log error messages for debugging:

```json theme={null}
{
  "error": "validation_failed",
  "error_description": "Field 'name' is required"
}
```

### 3. Handle Specific Errors

Handle specific error codes differently:

```python theme={null}
if error_code == "invalid_token":
    refresh_token()
elif error_code == "not_found":
    log_not_found(resource_name)
elif error_code == "validation_failed":
    show_validation_errors(error_description)
```

### 4. Retry Logic

Implement retry logic for transient errors (500, network errors):

```python theme={null}
max_retries = 3
for attempt in range(max_retries):
    try:
        response = make_request()
        if response.status_code == 200:
            return response
    except Exception as e:
        if attempt == max_retries - 1:
            raise
        time.sleep(2 ** attempt)  # Exponential backoff
```

### 5. Logging

Log errors for debugging and monitoring:

```python theme={null}
logger.error(f"API Error: {error_code} - {error_description}")
logger.debug(f"Request: {request_url}")
logger.debug(f"Response: {response_body}")
```

## Validation Errors

Validation errors may include field-specific information:

```json theme={null}
{
  "error": "validation_failed",
  "error_description": "Validation failed",
  "validation_errors": [
    {
      "field": "name",
      "message": "Name is required"
    },
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}
```

## Rate Limiting Errors

When rate limits are exceeded, you may receive:

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "error_description": "Rate limit exceeded. Please try again later.",
  "retry_after": 60
}
```

The `retry_after` field indicates seconds to wait before retrying.

## Troubleshooting

### Common Issues

<Steps>
  <Step title="401 Unauthorized">
    * Check token validity
    * Verify `Authorization` header format
    * Ensure token hasn't expired
  </Step>

  <Step title="404 Not Found">
    * Verify resource names (case-sensitive)
    * Check project/environment context
    * Ensure resource exists
  </Step>

  <Step title="400 Bad Request">
    * Validate request body against schema
    * Check required fields
    * Verify data types
  </Step>

  <Step title="500 Internal Server Error">
    * Retry the request
    * Check system status
    * Contact support if persistent
  </Step>
</Steps>

## Next Steps

* [Explore the API reference](/api-reference/overview) - Complete API endpoint documentation