Errors

When something goes wrong, the Minds API responds with an HTTP status code and a descriptive message. Use the status code to understand the category of failure, and the message (and named error type, where applicable) to understand the specifics.

Most errors are actionable — read the message before contacting support.

Status codes

  • Name
    2xx
    Description

    Success. 200 for most reads and updates, 201 for resource creation, 204 for empty-body responses (such as deletes).

  • Name
    400
    Description

    Bad request. The request was understood but semantically wrong — for example, the conversation's mind doesn't match the request, or you tried to fetch a SQL result from a message that has none. See the named error types below.

  • Name
    401
    Description

    Unauthorized. Your API key is missing or invalid. The production gateway at mdb.ai enforces authentication on every route — see Authentication.

  • Name
    403
    Description

    Forbidden. You're authenticated, but your role doesn't permit this action. Most commonly returned by admin-scoped endpoints.

  • Name
    404
    Description

    Not found. The mind, datasource, conversation, or item ID you referenced doesn't exist or isn't accessible to you.

  • Name
    409
    Description

    Conflict. The request conflicts with existing state — for example, a duplicate resource, or querying a data-catalog entry for a table or column that hasn't been cataloged yet.

  • Name
    422
    Description

    Unprocessable entity. The request body parses but fails validation (missing required field, wrong type, out-of-range value).

  • Name
    429
    Description

    Too many requests. You've exceeded a usage limit — most commonly enforced at mind creation, datasource creation, and question submission. See Rate Limits.

  • Name
    5xx
    Description

    Server error. Something went wrong on our side. Retry with backoff; if it persists, contact support with the request ID.

Named error types

Certain client-side failures carry a named type to disambiguate what went wrong. These are the ones a Text-to-SQL integration is most likely to encounter:

  • Name
    ConversationMindMismatchError
    Description

    Returned from POST /responses/ (400) when the conversation you're posting to was created for a different mind than the one named in the request. Either start a new conversation for the intended mind, or route the request to the mind that owns the conversation.

  • Name
    MessageNoSQLQueryError
    Description

    Returned from /result, /export, and /chart (400) when the target message has no SQL query attached. These endpoints operate on the output of the Text-to-SQL agent; messages that predate the agent's response (such as the user's question) will return this error.

Error response format

Errors are returned with the status code in the HTTP response and a JSON body containing a detail field:

Error response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "detail": "Message does not have a SQL query."
}

Check the status code first, then read detail. Log the request ID from the response headers if you need to contact support.

Was this page helpful?