Error Handling
API error codes and solutions
Table of Contents
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:
json
{
"error": "Error message"
}
Additional details are included for input validation failures:
json
{
"error": "Invalid input",
"details": [
{
"field": "status",
"message": "Invalid enum value. Expected 'open' | 'in_progress' | 'resolved' | 'closed'"
}
]
}
HTTP Status Codes
| Status Code | Description |
|---|---|
200 | Request successful |
201 | Resource created successfully |
400 | Bad request (validation failure) |
401 | Authentication failed (API Key missing or expired) |
403 | Insufficient permissions (required Scope missing) |
404 | Resource not found |
422 | Unprocessable request |
429 | Rate limit exceeded |
500 | Internal server error |
Common Error Scenarios
401 Unauthorized
The API Key is missing or invalid.
bash
# 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
Authorizationheader 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).
json
{
"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.
json
{
"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.
json
{
"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/jsonheader 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