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

# Errors

> Understanding and handling OpenMetadata API errors

# ErrorsThe OpenMetadata API uses conventional HTTP response codes to indicate the success or failure of an API request. Error responses include a JSON body with details about what went wrong.#### Error Response FormatAll error responses follow this structure:**code** `integer` *required*HTTP status code**errorType** `string` *required*Machine-readable error type**message** `string` *required*Human-readable error description```json Error Response theme={null}
{
  "code": 404,
  "errorType": "ENTITY_NOT_FOUND",
  "message": "Table with name [prod.analytics.customers] not found"
}
```## HTTP Status Codes### Success Codes (2xx)| Code | Description |
| - | - |
| `200 OK` | Request succeeded |
| `201 Created` | Resource created successfully |
| `202 Accepted` | Request accepted for async processing |
| `204 No Content` | Success with no response body |### Client Error Codes (4xx)| Code | Error Type | Description |
| - | - | - |
| `400` | `BAD_REQUEST` | Invalid request parameters or malformed JSON |
| `401` | `UNAUTHORIZED` | Missing or invalid authentication token |
| `403` | `FORBIDDEN` | Valid token but insufficient permissions |
| `404` | `ENTITY_NOT_FOUND` | Requested resource doesn't exist |
| `409` | `ENTITY_ALREADY_EXISTS` | Resource with same identifier exists |
| `409` | `ENTITY_LOCKED` | Entity is locked during deletion |
| `412` | `PRECONDITION_FAILED` | ETag mismatch on conditional update |
| `413` | `BULK_LIMIT_EXCEPTION` | Request payload exceeds size limits |
| `429` | `LIMITS_EXCEPTION` | Rate limit exceeded |### Server Error Codes (5xx)| Code | Error Type | Description |
| - | - | - |
| `500` | `INTERNAL_ERROR` | Unexpected server error |## Error Types Reference### BAD\_REQUESTReturned when the request is malformed or contains invalid parameters.**Common causes:**
<ul><li>Missing required fields</li>
<li>Invalid field values or types</li>
<li>Malformed JSON body</li>
<li>Invalid query parameters</li></ul>```json Example theme={null}
{
  "code": 400,
  "errorType": "BAD_REQUEST",
  "message": "Invalid value for parameter 'limit': must be between 1 and 1000"
}
```### ENTITY\_NOT\_FOUND

Returned when the requested resource doesn't exist.



\**Variants:**
\<ul><li>Entity with id [<id>] not found</li>
  \<li>Entity with name [<fqn>] not found</li>
  \<li>Entity not found for query params [<params>]</li></ul>


    

\```json Example theme={null}
\{
  "code": 404,
  "errorType": "ENTITY_NOT_FOUND",
  "message": "Entity with id [550e8400-e29b-41d4-a716-446655440000] not found"
}
\```

### ENTITY\_ALREADY\_EXISTSReturned when attempting to create a resource that already exists.**Resolution:** Use PUT for upsert operations or verify the entity doesn't exist before creating.```json Example theme={null}
{
  "code": 409,
  "errorType": "ENTITY_ALREADY_EXISTS",
  "message": "Entity already exists"
}
```### UNAUTHORIZEDReturned when authentication fails.**Common causes:**
<ul><li>Missing Authorization header</li>
<li>Invalid or malformed token</li>
<li>Expired token</li>
<li>Token used after logout</li></ul>```json Example theme={null}
{
  "code": 401,
  "errorType": "UNAUTHORIZED",
  "message": "Token has expired"
}
```### FORBIDDENReturned when the authenticated user lacks permission for the operation.**Resolution:** Ensure the user or bot has the required role/policy for the operation.```json Example theme={null}
{
  "code": 403,
  "errorType": "FORBIDDEN",
  "message": "User does not have permission to delete table"
}
```### PRECONDITION\_FAILEDReturned when a conditional update fails due to version mismatch.**Resolution:** Fetch the latest version and retry with the updated ETag.```json Example theme={null}
{
  "code": 412,
  "errorType": "PRECONDITION_FAILED",
  "message": "Entity version mismatch"
}
```### LIMITS\_EXCEPTIONReturned when rate limits are exceeded.**Resolution:** Implement exponential backoff and retry logic.```json Example theme={null}
{
  "code": 429,
  "errorType": "LIMITS_EXCEPTION",
  "message": "Rate limit exceeded. Please retry after 60 seconds"
}
```## Handling Errors```python Python SDK theme={null}
from metadata.ingestion.ometa.ometa_api import OpenMetadata
from metadata.generated.schema.entity.data.table import Table

metadata = OpenMetadata(config)

try:
    # Attempt to get a table
    table = metadata.get_by_name(entity=Table, fqn="prod.analytics.customers")
except Exception as e:
    if "404" in str(e):
        print("Table not found")
    elif "401" in str(e):
        print("Authentication failed - check your token")
    elif "403" in str(e):
        print("Permission denied")
    else:
        print(f"API error: {e}")
``````java JAVA SDK theme={null}
import org.openmetadata.sdk.exceptions.OpenMetadataException;

// client is an initialized OpenMetadataClient.

try {
    var table = client.tables().getByName("prod.analytics.customers");
} catch (OpenMetadataException e) {
    switch (e.getStatusCode()) {
        case 404:
            System.out.println("Table not found");
            break;
        case 401:
            System.out.println("Authentication failed");
            break;
        case 403:
            System.out.println("Permission denied");
            break;
        default:
            System.out.println("API error: " + e.getMessage());
    }
}
``````bash HTTP (cURL with error handling) theme={null}
response=$(curl -s -w "\n%{http_code}" \
  -X GET "https://your-company.open-metadata.org/api/v1/tables/name/prod.analytics.customers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json")

http_code=$(echo "$response" | tail -n1)
body=$(echo "$response" | sed '$d')

case $http_code in
  200)
    echo "Success: $body"
    ;;
  404)
    echo "Table not found"
    ;;
  401)
    echo "Authentication failed"
    ;;
  403)
    echo "Permission denied"
    ;;
  *)
    echo "Error $http_code: $body"
    ;;
esac
```## Validation ErrorsWhen request validation fails, the error message includes details about which field(s) failed:```json Validation Error theme={null}
{
  "code": 400,
  "errorType": "BAD_REQUEST",
  "message": "query param limit must be greater than 0"
}
```For JSON body validation errors:```json JSON Validation Error theme={null}
{
  "code": 400,
  "errorType": "BAD_REQUEST",
  "message": "name is required and cannot be empty"
}
```## Retry LogicFor transient errors (5xx, 429), implement retry with exponential backoff:```python Retry theme={null}
import time
import random

def api_call_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if "429" in str(e) or "500" in str(e):
                # Exponential backoff with jitter
                wait_time = (2 ** attempt) + random.uniform(0, 1)
                print(f"Retrying in {wait_time:.2f}s...")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Max retries exceeded")
```## Debugging Tips**1. Check the error message**The `message` field usually contains specific details about what went wrong.**2. Verify authentication**Ensure your token is valid and not expired. Try generating a new token.**3. Check permissions**For 403 errors, verify the user/bot has the required role for the operation.**4. Validate request format**For 400 errors, check that all required fields are present and properly formatted.**5. Check resource existence**For 404 errors, verify the resource exists and the FQN/ID is correct.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.