Error Codes Reference

Comprehensive list of API error codes with causes and solutions.

Error Response Format

All errors follow this consistent structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": { ... }
  },
  "meta": {
    "request_id": "req_abc123xyz"
  }
}

Error Handling Example

async function extractMetadata(url: string) {
  const response = await fetch(
    `https://api.katsau.com/v1/extract?url=${encodeURIComponent(url)}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );

  const data = await response.json();

  if (!data.success) {
    // Handle specific error codes
    switch (data.error.code) {
      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        await sleep(parseInt(response.headers.get('Retry-After') || '5') * 1000);
        return extractMetadata(url);

      case 'TARGET_TIMEOUT':
        // Try with longer timeout or skip
        console.warn(`Timeout for ${url}, skipping...`);
        return null;

      case 'INVALID_URL':
        throw new Error(`Invalid URL: ${url}`);

      default:
        throw new Error(`API Error: ${data.error.message}`);
    }
  }

  return data.data;
}

HTTP Status Codes

200Success

201Created

400Bad Request

401Unauthorized

403Forbidden

404Not Found

429Rate Limited

500Server Error

502Bad Gateway

Authentication Errors

MISSING_API_KEY401

No API key provided in request

Cause

The Authorization header is missing or empty

Solution

Add the Authorization header with your API key: Authorization: Bearer ks_live_xxx

INVALID_API_KEY401

API key is malformed or does not exist

Cause

The API key format is wrong or was deleted

Solution

Check your API key in the dashboard. Keys should start with ks_live_ or ks_test_

API_KEY_REVOKED401

API key has been revoked

Cause

The key was manually revoked from the dashboard

Solution

Generate a new API key from the dashboard and update your application

API_KEY_EXPIRED401

API key has expired

Cause

Test keys expire after 30 days of inactivity

Solution

Create a new test key or upgrade to a live key for permanent access

Validation Errors

MISSING_URL400

Required URL parameter not provided

Cause

The url query parameter is missing from the request

Solution

Add the url parameter: /v1/extract?url=https://example.com

INVALID_URL400

URL is malformed or uses unsupported protocol

Cause

The URL format is invalid or uses a protocol other than http/https

Solution

Ensure the URL starts with http:// or https:// and is properly encoded

URL_TOO_LONG400

URL exceeds maximum length

Cause

URLs longer than 2048 characters are not supported

Solution

Use a URL shortener or reduce query parameters in the target URL

INVALID_PARAMETER400

One or more parameters have invalid values

Cause

A parameter value is outside accepted range or wrong type

Solution

Check the API documentation for valid parameter values

INVALID_BODY400

Request body is not valid JSON

Cause

POST request body contains malformed JSON

Solution

Validate your JSON using a JSON linter before sending

Rate Limiting Errors

RATE_LIMIT_EXCEEDED429

Too many requests in a short time window

Cause

You have exceeded the requests per second limit for your plan

Solution

Implement exponential backoff. Check X-RateLimit-Reset header for retry time

// Implement retry with exponential backoff
async function fetchWithRetry(url, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url);
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      continue;
    }
    return response;
  }
  throw new Error('Max retries exceeded');
}

QUOTA_EXCEEDED403

Monthly request quota has been reached

Cause

You have used all requests included in your plan for this billing period

Solution

Upgrade your plan or wait for the next billing cycle to reset your quota

CONCURRENT_LIMIT429

Too many concurrent requests

Cause

You have exceeded the maximum number of parallel requests

Solution

Queue requests and limit concurrency. Use Promise.all with batching

Target URL Errors

TARGET_UNREACHABLE502

Could not connect to target URL

Cause

The target server is down, blocking our requests, or DNS resolution failed

Solution

Verify the URL is accessible. Some sites block automated requests

TARGET_TIMEOUT504

Target URL did not respond in time

Cause

The target server took longer than 10 seconds to respond

Solution

The target site may be slow. Try again later or use caching

TARGET_BLOCKED403

Target URL blocked our request

Cause

The target site has bot protection or blocks our IP range

Solution

Some sites cannot be scraped. Consider using their official API instead

TARGET_SSL_ERROR502

SSL/TLS certificate validation failed

Cause

The target site has an invalid or expired SSL certificate

Solution

Contact the target site owner to fix their SSL certificate

ROBOTS_BLOCKED403

Target URL disallows crawling via robots.txt

Cause

The site robots.txt file blocks automated access

Solution

Respect robots.txt or contact the site owner for permission

Content Errors

PARSE_ERROR422

Could not parse page content

Cause

The HTML is malformed or uses unsupported encoding

Solution

Ensure the target page returns valid HTML with proper charset

NO_METADATA422

No metadata found on page

Cause

The page has no Open Graph, Twitter Card, or standard meta tags

Solution

The page may be a SPA that requires JavaScript rendering

CONTENT_TOO_LARGE413

Page content exceeds size limit

Cause

The HTML response is larger than 10MB

Solution

We cannot process extremely large pages. Contact support for enterprise limits

Server Errors

INTERNAL_ERROR500

An unexpected server error occurred

Cause

Something went wrong on our end

Solution

Retry the request. If persistent, contact support with the request_id

SERVICE_UNAVAILABLE503

Service temporarily unavailable

Cause

We are experiencing high load or performing maintenance

Solution

Wait a few minutes and retry. Check status.katsau.com for updates

Error Handling Best Practices

Always check the success field before accessing response data
Log the request_id from the meta object for debugging
Implement exponential backoff for rate limit and server errors
Use the error code for programmatic error handling, not the message
Monitor rate limit headers (X-RateLimit-*) to avoid hitting limits