Error codes

API v1 returns two error shapes depending on where the failure occurs:

Resource errors (validation and not-found errors raised inside an endpoint) return a nested object: { "error": { "code", "message" } }. Use the code for programmatic handling.
Gateway errors raised before an endpoint runs return a flat object: { "error", "message" }. This includes 401, 429, and an authentication-layer 500. Here error is a status label, not a machine-readable code.

Always branch on the HTTP status first, then read the body in the shape matching that status.

HTTP status codes

Code	Status	Description
200	OK	Request succeeded
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource doesn’t exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error

Error response formats

Resource errors (nested)

Validation and not-found errors raised inside an endpoint return a structured error object:

{
  "error": {
    "code": "BRAND_NOT_FOUND",
    "message": "Brand not found or not accessible"
  }
}

object

Show Error object

string

Machine-readable error code for programmatic handling

string

Human-readable error description

Gateway errors (flat)

Gateway responses use a flat shape. error is a status label, not a code:

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

string

Short status label (e.g. Unauthorized, Too Many Requests).

string

Human-readable description of the failure.

429 responses additionally include limit ("burst" or "daily") and retryAfter (seconds).

Error code reference

Authorization

Code	HTTP Status	Description
`INSUFFICIENT_PLAN`	403	Growth plan or higher required
`FORBIDDEN`	403	Access denied

Authentication 401 responses are flat and do not contain these resource codes.

Not found

Code	HTTP Status	Description
`BRAND_NOT_FOUND`	404	Brand not found or not accessible
`COMPETITOR_NOT_FOUND`	404	Competitor not found
`SOURCE_NOT_FOUND`	404	Source not found
`PROMPT_NOT_FOUND`	404	Prompt not found
`ANSWER_NOT_FOUND`	404	Answer not found
`KEYWORD_NOT_FOUND`	404	Topic not found
`TAG_NOT_FOUND`	404	Tag not found
`PITCH_AUDIT_NOT_FOUND`	404	Pitch Audit not found or inaccessible
`RESOURCE_NOT_FOUND`	404	Generic resource not found
`ENDPOINT_NOT_FOUND`	404	API endpoint does not exist

Bad request

Code	HTTP Status	Description
`INVALID_REQUEST`	400	Invalid request format
`INVALID_PARAMETER`	400	Invalid parameter value
`MISSING_PARAMETER`	400	Missing required parameter
`INVALID_DATE_RANGE`	400	Invalid date range
`INVALID_SORT_FIELD`	400	Invalid sort field

Rate limiting

Gateway 429 responses are flat. Use the HTTP status, limit, retryAfter, and Retry-After header instead of expecting a nested error code.

Server errors

Code	HTTP Status	Description
`INTERNAL_ERROR`	500	Internal server error

Common errors

Authentication errors (401)

Authentication failures use the flat shape:

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

// Invalid token, revoked token, or plan below Growth
{
  "error": "Unauthorized",
  "message": "Invalid API token or insufficient subscription plan (Growth+ required)"
}

Check the Bearer prefix, token status, team status, and active plan.

Permission errors (403)

// Team subscription doesn't include API access
{
  "error": {
    "code": "INSUFFICIENT_PLAN",
    "message": "Growth plan or higher required"
  }
}

Verify the resource-specific permission or plan requirement.

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"
  }
}

Check that the resource ID belongs to the team associated with the token.

Rate-limit errors (429)

Rate-limit responses use the flat shape and add limit and retryAfter:

{
  "error": "Too Many Requests",
  "limit": "burst",
  "message": "Per-minute rate limit exceeded. Please try again in 45 seconds.",
  "retryAfter": 45
}

limit is "burst" (per-minute) or "daily". Honor the Retry-After header before retrying. See Rate limits.

Server errors (500)

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Retry transient failures with bounded backoff. If the error persists, contact support with the endpoint and request timestamp.

Handle errors

JavaScript/TypeScript example

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

  if (!response.ok) {
    const data = await response.json().catch(() => ({}));

    // Gateway errors use the flat shape: { error, message }
    if (response.status === 401) {
      throw new Error(`Authentication failed: ${data.message ?? data.error}`);
    }
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') ?? data.retryAfter;
      throw new Error(`Rate limited. Retry after ${retryAfter} second(s).`);
    }

    // Resource errors use the nested shape: { error: { code, message } }
    const nestedError = typeof data.error === 'object' ? data.error : null;
    const code = nestedError?.code ?? `HTTP_${response.status}`;
    const message = nestedError?.message ?? data.message ?? data.error ?? `HTTP ${response.status}`;

    switch (code) {
      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}`);
      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://www.qwairy.co/api/v1{endpoint}",
        headers={"Authorization": f"Bearer {os.environ['QWAIRY_API_TOKEN']}"}
    )

    if not response.ok:
        body = response.json() if response.content else {}

        # Gateway errors use the flat shape: { error, message }
        if response.status_code == 401:
            raise Exception(f"Authentication failed: {body.get('message', body.get('error'))}")
        if response.status_code == 429:
            retry_after = response.headers.get('Retry-After', body.get('retryAfter'))
            raise Exception(f"Rate limited. Retry after {retry_after} second(s).")

        # Resource errors use the nested shape: { error: { code, message } }
        error = body.get('error', {}) if isinstance(body.get('error'), dict) else {}
        code = error.get('code', 'UNKNOWN')
        message = error.get('message', body.get('message', 'Unknown error'))

        if code in ['INSUFFICIENT_PLAN', 'FORBIDDEN']:
            raise Exception(f"Permission denied: {message}")
        elif code.endswith('_NOT_FOUND'):
            raise Exception(f"Not found: {message}")
        else:
            raise Exception(f"API error [{code}]: {message}")

    return response.json()

Get help

If you encounter persistent errors or unexpected behavior, contact us at team@qwairy.co with:

The endpoint you’re calling
The full error response
Your request headers (without the token)
The timestamp of the request

Get started

Configure data

Monitor and measure

Analyze and act

Agency and automation

Implementation guides

HTTP status codes

Error response formats

Resource errors (nested)

Gateway errors (flat)

Error code reference

Authorization

Not found

Bad request

Rate limiting

Server errors

Common errors

Authentication errors (401)

Permission errors (403)

Not-found errors (404)

Rate-limit errors (429)

Server errors (500)

Handle errors

JavaScript/TypeScript example

Python example

Get help

​HTTP status codes

​Error response formats

​Resource errors (nested)

​Gateway errors (flat)

​Error code reference

​Authorization

​Not found

​Bad request

​Rate limiting

​Server errors

​Common errors

​Authentication errors (401)

​Permission errors (403)

​Not-found errors (404)

​Rate-limit errors (429)

​Server errors (500)

​Handle errors

​JavaScript/TypeScript example

​Python example

​Get help

HTTP status codes

Error response formats

Resource errors (nested)

Gateway errors (flat)

Error code reference

Authorization

Not found

Bad request

Rate limiting

Server errors

Common errors

Authentication errors (401)

Permission errors (403)

Not-found errors (404)

Rate-limit errors (429)

Server errors (500)

Handle errors

JavaScript/TypeScript example

Python example

Get help