Error Handling

The QA Note API returns standard HTTP status codes and JSON-formatted error responses.

Error Response Format

All error responses follow this format:

{
  "error": "Error message"
}

Additional details are included for input validation failures:

{
  "error": "Invalid input",
  "details": [
    {
      "field": "status",
      "message": "Invalid enum value. Expected 'open' | 'in_progress' | 'blocked' | 'fix_submitted' | 'verified' | 'closed'"
    }
  ]
}

HTTP Status Codes

Common Error Scenarios

401 Unauthorized

The API Key is missing or invalid.

# Incorrect — Authorization header missing
curl https://qanote.app/api/v1/projects

# Correct
curl https://qanote.app/api/v1/projects \
  -H "Authorization: Bearer qn_YOUR_API_KEY"

Solution:

• Verify the Authorization header is included
• Confirm the API Key starts with qn_
• Check the API Key hasn't expired in the dashboard

403 Forbidden

The API Key doesn't have the required permission (Scope).

{
  "error": "Insufficient scope"
}

Solution:

• Check the API Key's Scope settings in the dashboard
• Reading issues: requires issues:read
• Modifying issues/writing comments: requires issues:write
• Listing projects: requires projects:read

404 Not Found

The requested resource (project, issue, etc.) doesn't exist or doesn't belong to the API Key's organization.

{
  "error": "Project not found"
}

Solution:

• Verify the project ID or issue number is correct
• Confirm the resource belongs to the API Key's organization

400 Bad Request

Request body validation failed.

{
  "error": "Invalid input",
  "details": [
    {
      "field": "priority",
      "message": "Invalid enum value. Expected 'low' | 'medium' | 'high' | 'critical'"
    }
  ]
}

Solution:

• Verify the request body is valid JSON
• Confirm the Content-Type: application/json header is included
• Ensure parameter values are within allowed ranges

429 Too Many Requests

API request rate limit exceeded.

Solution:

• Wait a moment and try again
• Implement retry logic with intervals between requests
• Reduce unnecessary repeated requests