Skip to main content

Errors

The 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.

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

ENTITY_NOT_FOUND

ENTITY_ALREADY_EXISTS

UNAUTHORIZED

FORBIDDEN

PRECONDITION_FAILED

LIMITS_EXCEPTION

Handling Errors

Python SDK

Validation Errors

When request validation fails, the error message includes details about which field(s) failed:
For JSON body validation errors:

Retry Logic

For transient errors (5xx, 429), implement retry with exponential backoff:

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.