Skip to main content

​
Errors

The Collate 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 Format

{
  "code": 404,
  "errorType": "ENTITY_NOT_FOUND",
  "message": "Table with name [prod.analytics.customers] not found"
}

​
HTTP Status Codes

​
Success Codes (2xx)

CodeDescription
200 OKRequest succeeded
201 CreatedResource created successfully
202 AcceptedRequest accepted for async processing
204 No ContentSuccess with no response body

​
Client Error Codes (4xx)

CodeError TypeDescription
400BAD_REQUESTInvalid request parameters or malformed JSON
401UNAUTHORIZEDMissing or invalid authentication token
403FORBIDDENValid token but insufficient permissions
404ENTITY_NOT_FOUNDRequested resource doesn’t exist
409ENTITY_ALREADY_EXISTSResource with same identifier exists
409ENTITY_LOCKEDEntity is locked during deletion
412PRECONDITION_FAILEDETag mismatch on conditional update
413BULK_LIMIT_EXCEPTIONRequest payload exceeds size limits
429LIMITS_EXCEPTIONRate limit exceeded

​
Server Error Codes (5xx)

CodeError TypeDescription
500INTERNAL_ERRORUnexpected server error

​
Error Types Reference

​
BAD_REQUEST

{
  "code": 400,
  "errorType": "BAD_REQUEST",
  "message": "Invalid value for parameter 'limit': must be between 1 and 1000"
}

​
ENTITY_NOT_FOUND

{
  "code": 404,
  "errorType": "ENTITY_NOT_FOUND",
  "message": "Entity with id [550e8400-e29b-41d4-a716-446655440000] not found"
}

​
ENTITY_ALREADY_EXISTS

{
  "code": 409,
  "errorType": "ENTITY_ALREADY_EXISTS",
  "message": "Entity already exists"
}

​
UNAUTHORIZED

{
  "code": 401,
  "errorType": "UNAUTHORIZED",
  "message": "Token has expired"
}

​
FORBIDDEN

{
  "code": 403,
  "errorType": "FORBIDDEN",
  "message": "User does not have permission to delete table"
}

​
PRECONDITION_FAILED

{
  "code": 412,
  "errorType": "PRECONDITION_FAILED",
  "message": "Entity version mismatch"
}

​
LIMITS_EXCEPTION

{
  "code": 429,
  "errorType": "LIMITS_EXCEPTION",
  "message": "Rate limit exceeded. Please retry after 60 seconds"
}

​
Handling Errors

Python SDK
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}")

​
Validation Errors

When request validation fails, the error message includes details about which field(s) failed: 
{
  "code": 400,
  "errorType": "BAD_REQUEST",
  "message": "query param limit must be greater than 0"
}
For JSON body validation errors: 
{
  "code": 400,
  "errorType": "BAD_REQUEST",
  "message": "name is required and cannot be empty"
}

​
Retry Logic

For transient errors (5xx, 429), implement retry with exponential backoff: 
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.