When using JQL, errors may occur due to a variety of reasons, such as incorrect query syntax, invalid data, or issues with authentication. Understanding the error codes and messages returned by JQL is crucial for diagnosing and resolving these issues effectively.

Common Error Codes and Their Meanings

Below is a list of common error codes you might encounter when working with JQL, along with their meanings:

• 400 Bad Request

  • Error Code: JQL:JqlException
  • Description: This indicates that the query is malformed or contains invalid parameters. It could be due to syntax errors, missing required fields, or incorrect data types.
  • Example Error Message: "errorMessage": "Invalid query syntax"

• 401 Unauthorized

  • Error Code: JQL:AuthenticationException
  • Description: This error occurs when the query fails to authenticate. This could be due to missing or invalid authentication credentials, such as an expired JWT token or incorrect session data.
  • Example Error Message: "errorMessage": "Authentication failed"

• 403 Forbidden

  • Error Code: JQL:AuthorizationException
  • Description: The user does not have the necessary permissions to perform the requested operation. This could happen if the user tries to access a resource or perform an action they are not authorized to.
  • Example Error Message: "errorMessage": "You do not have permission to access this resource"

• 404 Not Found

  • Error Code: JQL:NotFoundException
  • Description: The specified resource could not be found. This could happen if the query references an ID that does not exist in the database or if the resource has been deleted.
  • Example Error Message: "errorMessage": "Resource not found"

• 500 Internal Server Error

  • Error Code: JQL:ServerException
  • Description: This indicates a server-side error, which could be due to a bug in the backend, a failed database operation, or other unforeseen issues.
  • Example Error Message: "errorMessage": "An unexpected error occurred"

• 503 Service Unavailable

  • Error Code: JQL:ServiceUnavailableException
  • Description: This error occurs when the server is temporarily unable to handle the request, often due to maintenance or overload.
  • Example Error Message: "errorMessage": "Service is temporarily unavailable"

Guidance on Interpreting Error Messages

When an error occurs, JQL returns a structured error response that provides detailed information about the issue. Here's a breakdown of how to interpret the key components of an error message:

• status: Indicates the overall status of the operation. In the case of an error, this will be "ERROR".
• data: This field is typically null in error responses since no data could be retrieved or processed.
• errors: This is an array that contains detailed error information. Each error object in the array includes:
  • statusCode: The HTTP status code corresponding to the error (e.g., 400, 401, 404).
  • errorCode: A specific code that identifies the type of error. This is useful for categorizing and handling different types of errors programmatically.
  • errorPayload: Additional data related to the error, if available. This could include information about the part of the query that caused the error.
  • errorMessage: A human-readable message that provides more details about the error. This message can help diagnose what went wrong.

Example Error Response:

{
    "status": "ERROR",
    "data": null,
    "errors": [
        {
            "statusCode": "400",
            "errorCode": "JQL:JqlException",
            "errorPayload": "None",
            "errorMessage": "Invalid query syntax in 'filter' field"
        }
    ],
    "il8n": "en-gb",
    "extras": null,
    "system_info": null,
    "intent": null,
    "message": null
}

In this example:

• statusCode: 400 indicates that the error is due to a bad request.
• errorCode: JQL:JqlException points to a generic JQL exception.
• errorPayload: None suggests there is no additional data related to the error.
• errorMessage: "Invalid query syntax in 'filter' field" provides a clear explanation of the issue, helping you quickly identify and correct the problem in your query.

Handling Errors

When an error is encountered, it’s important to:

1. Review the errorMessage to understand the specific issue.
2. Check the statusCode to determine the general category of the error (e.g., client-side vs. server-side).
3. Investigate the errorCode for more technical insight, especially if you need to programmatically respond to different types of errors.
4. Correct the query or address the underlying issue, such as authentication problems, and retry the operation.