Skip to main content
All errors return a JSON object with a structured error field containing a machine-readable code and a human-readable message. Use the error codes for programmatic error handling.

​
HTTP Status Codes

CodeStatusDescription
200OKRequest succeeded
400Bad RequestInvalid request parameters
401UnauthorizedMissing or invalid authentication
403ForbiddenValid auth but insufficient permissions
404Not FoundResource doesn’t exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error

​
Error Response Format

All errors return a JSON response with a structured error object: 
{
  "error": {
    "code": "BRAND_NOT_FOUND",
    "message": "Brand not found or not accessible"
  }
}
​
error
object

​
Error Codes Reference

​
Authentication & Authorization

CodeHTTP StatusDescription
UNAUTHORIZED401Authentication required
INVALID_TOKEN401Invalid or expired API token
INSUFFICIENT_PLAN403Business plan or higher required
FORBIDDEN403Access denied

​
Not Found

CodeHTTP StatusDescription
BRAND_NOT_FOUND404Brand not found or not accessible
COMPETITOR_NOT_FOUND404Competitor not found
SOURCE_NOT_FOUND404Source not found
PROMPT_NOT_FOUND404Prompt not found
ANSWER_NOT_FOUND404Answer not found
RESOURCE_NOT_FOUND404Generic resource not found
ENDPOINT_NOT_FOUND404API endpoint does not exist

​
Bad Request

CodeHTTP StatusDescription
INVALID_REQUEST400Invalid request format
INVALID_PARAMETER400Invalid parameter value
MISSING_PARAMETER400Missing required parameter
INVALID_DATE_RANGE400Invalid date range
INVALID_SORT_FIELD400Invalid sort field

​
Rate Limiting

CodeHTTP StatusDescription
RATE_LIMIT_EXCEEDED429Rate limit exceeded

​
Server Errors

CodeHTTP StatusDescription
INTERNAL_ERROR500Internal server error

​
Common Errors

​
Authentication Errors (401)

// Missing Authorization header
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header. Use: Authorization: Bearer qw-api-xxx"
  }
}

// Invalid or revoked token
{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Invalid or expired API token"
  }
}
Solution: Ensure you’re using a valid token with the correct Bearer prefix.

​
Permission Errors (403)

// Team subscription doesn't include API access
{
  "error": {
    "code": "INSUFFICIENT_PLAN",
    "message": "Business plan or higher required"
  }
}
Solution: Verify you have the correct permissions and plan level.

​
Not Found Errors (404)

// Brand doesn't exist
{
  "error": {
    "code": "BRAND_NOT_FOUND",
    "message": "Brand not found or not accessible"
  }
}

// Competitor doesn't exist
{
  "error": {
    "code": "COMPETITOR_NOT_FOUND",
    "message": "Competitor not found"
  }
}
Solution: Check that the resource ID is correct and belongs to your team.

​
Rate Limit Errors (429)

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again in 45 seconds."
  }
}
Solution: Wait until X-RateLimit-Reset timestamp, then retry. See Rate Limits.

​
Server Errors (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}
Solution: Retry after a few seconds. If the error persists, contact support.

​
Handling Errors

​
JavaScript/TypeScript Example

async function callQwairyAPI(endpoint: string) {
  const response = await fetch(`https://qwairy.co/api/v1${endpoint}`, {
    headers: {
      'Authorization': `Bearer ${process.env.QWAIRY_API_TOKEN}`,
    },
  });

  if (!response.ok) {
    const data = await response.json();
    const { code, message } = data.error;

    switch (code) {
      case 'UNAUTHORIZED':
      case 'INVALID_TOKEN':
        throw new Error(`Authentication failed: ${message}`);
      case 'INSUFFICIENT_PLAN':
      case 'FORBIDDEN':
        throw new Error(`Permission denied: ${message}`);
      case 'BRAND_NOT_FOUND':
      case 'COMPETITOR_NOT_FOUND':
      case 'SOURCE_NOT_FOUND':
      case 'PROMPT_NOT_FOUND':
      case 'ANSWER_NOT_FOUND':
        throw new Error(`Resource not found: ${message}`);
      case 'RATE_LIMIT_EXCEEDED':
        const resetTime = response.headers.get('X-RateLimit-Reset');
        throw new Error(`Rate limited. Retry after: ${resetTime}`);
      default:
        throw new Error(`API error [${code}]: ${message}`);
    }
  }

  return response.json();
}

​
Python Example

import requests
import os

def call_qwairy_api(endpoint):
    response = requests.get(
        f"https://qwairy.co/api/v1{endpoint}",
        headers={"Authorization": f"Bearer {os.environ['QWAIRY_API_TOKEN']}"}
    )

    if not response.ok:
        error = response.json().get('error', {})
        code = error.get('code', 'UNKNOWN')
        message = error.get('message', 'Unknown error')

        if code in ['UNAUTHORIZED', 'INVALID_TOKEN']:
            raise Exception(f"Authentication failed: {message}")
        elif code in ['INSUFFICIENT_PLAN', 'FORBIDDEN']:
            raise Exception(f"Permission denied: {message}")
        elif code.endswith('_NOT_FOUND'):
            raise Exception(f"Not found: {message}")
        elif code == 'RATE_LIMIT_EXCEEDED':
            reset_time = response.headers.get('X-RateLimit-Reset')
            raise Exception(f"Rate limited. Retry after: {reset_time}")
        else:
            raise Exception(f"API error [{code}]: {message}")

    return response.json()

​
Need Help?

If you encounter persistent errors or unexpected behavior, contact us at [email protected] with:
  • The endpoint you’re calling
  • The full error response
  • Your request headers (without the token)
  • The timestamp of the request