Error Handling

The MindKey Connector API uses standard HTTP status codes to indicate the outcome of requests. This section describes the status codes you may encounter and the format of error responses.

HTTP Status Codes

Status Code	Meaning	Description
200 OK	Success	The request was successful and data is returned in the response body.
400 Bad Request	Invalid query	The OData query in the URL is not valid. The response body contains details about the error.
401 Unauthorized	Authentication failed	The request did not include valid credentials, or the API key has expired.
404 Not Found	Resource not found	The requested endpoint does not exist, or you do not have the required scope to access it.

info

For security reasons, the API returns 404 Not Found rather than 403 Forbidden when you lack the required scope for an endpoint. This prevents discovery of endpoints that exist but are outside your authorized scopes.

Error Response Format

When the API returns a 400 Bad Request due to an invalid OData query, the response body contains an error object with a descriptive message:

{
    "Message": "The query specified in the URI is not valid. Could not find a property named 'invalidProperty' on type 'Employee'."
}

Common causes for 400 Bad Request responses include:

• Referencing a property name that does not exist on the entity.
• Using an unsupported query parameter or operator.
• Malformed $filter expressions (e.g., missing comparison operator or value).
• Invalid syntax in $expand or $select clauses.

Raw Query Mode

By default, the API applies property name mappings when processing OData queries and returning results. In some cases, you may need to bypass this mapping and work directly with the underlying property names.

To enable raw query mode, include the mindkey.raw=true parameter in the Accept header:

GET /odata/v2/Employee HTTP/1.1
Host: connector.mindkey.com
Authorization: ApiKey-v2 YOUR_API_KEY
Accept: application/json; mindkey.raw=true

In raw mode, the response uses the internal property names rather than the mapped OData names. This is an advanced feature intended for specific integration scenarios.

warning

Raw query mode is not part of the standard API contract and property names may change between releases. Use this only when explicitly needed.