Error Handling

The Respectify API follows standard REST conventions for error handling:

HTTP 200: Success. Response body contains the documented schema for that endpoint (e.g., CommentScore, SpamDetectionResult).
HTTP 4xx/5xx: Error. Response body contains a standard Error object with error, message, and code fields.

All language SDKs provide typed exceptions for different error conditions—the libraries wrap HTTP REST interaction and surface errors as exceptions. Catch these to handle specific failure modes in your application.

Exception Reference

AuthenticationError (401)

TypeScript
Python
PHP

AuthenticationError

UnauthorizedException

Raised when your email or API key is invalid, or the API key has been revoked.

Common causes:

Typo in email or API key
API key was revoked from the dashboard

BadRequestError (400)

TypeScript
Python
PHP

BadRequestError

Raised when the request parameters are invalid.

Common causes:

Empty comment text (e.g., passing an empty string to evaluateComment, checkSpam, checkRelevance, etc.)
Invalid article ID (malformed UUID, or an ID that doesn't exist)
Missing required parameters

BadRequestError

Raised when the request parameters are invalid.

Common causes:

Empty comment text (e.g., passing an empty string to evaluate_comment, check_spam, check_relevance, etc.)
Invalid article ID (malformed UUID, or an ID that doesn't exist)
Missing required parameters

BadRequestException

Raised when the request parameters are invalid.

Common causes:

Empty comment text (e.g., passing an empty string to evaluateComment, checkSpam, checkRelevance, etc.)
Invalid article ID (malformed UUID, or an ID that doesn't exist)
Missing required parameters

PaymentRequiredError (402)

TypeScript
Python
PHP

PaymentRequiredError

PaymentRequiredException

Raised when your subscription doesn't cover the requested endpoint, or has expired.

Common causes:

Subscription has lapsed
Trying to use a feature not included in your plan

UnsupportedMediaTypeError (415)

TypeScript
Python
PHP

UnsupportedMediaTypeError

Raised when calling initTopicFromUrl and the URL points to a file type that Respectify cannot parse.

Supported formats: HTML pages, Markdown files, PDF documents, plain text files.

Common causes:

URL points to an image, video, or binary file
URL points to a document type like .docx or .xlsx
Server returns an unexpected Content-Type header

What to do: Use initTopicFromText instead, or contact us to request support for the format you need.

UnsupportedMediaTypeError

Raised when calling init_topic_from_url and the URL points to a file type that Respectify cannot parse.

Supported formats: HTML pages, Markdown files, PDF documents, plain text files.

Common causes:

URL points to an image, video, or binary file
URL points to a document type like .docx or .xlsx
Server returns an unexpected Content-Type header

What to do: Use init_topic_from_text instead, or contact us to request support for the format you need.

UnsupportedMediaTypeException

Raised when calling initTopicFromUrl and the URL points to a file type that Respectify cannot parse.

Supported formats: HTML pages, Markdown files, PDF documents, plain text files.

Common causes:

URL points to an image, video, or binary file
URL points to a document type like .docx or .xlsx
Server returns an unexpected Content-Type header

What to do: Use initTopicFromText instead, or contact us to request support for the format you need.

ServerError (500)

TypeScript
Python
PHP

ServerError

ServerException

Raised when something goes wrong on the Respectify server.

What to do: Retry after a short delay. If the error persists, contact support with the full error message and request details so we can investigate.

ResponseParseError (TypeScript only)

ResponseParseError

Raised when the API returns invalid JSON or an unexpected response structure.

What to do: This usually indicates a transient server issue. Retry after a short delay.

Error Response Format

All non-200 HTTP responses return a JSON object with this structure:

Field	Type	Description
`error`	string	Short error title (e.g., "Unauthorized", "Missing Parameter")
`message`	string	Detailed error message explaining what went wrong
`code`	integer	HTTP status code (same as the response status)

Example:

{
  "error": "Subscription required",
  "message": "An active subscription is required to access this API.",
  "code": 402
}

Basic Error Handling

TypeScript
Python
PHP
REST API

import {
  RespectifyClient,
  AuthenticationError,
  BadRequestError,
  PaymentRequiredError,
  UnsupportedMediaTypeError,
  ServerError,
} from "@respectify/client";

const client = new RespectifyClient({ email, apiKey });

try {
  const result = await client.checkSpam("test comment", articleId);
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.error(`Auth failed: ${e.message}`);
    // Check your email and API key
  } else if (e instanceof BadRequestError) {
    console.error(`Bad request: ${e.message}`);
    // Check comment text isn't empty, articleId is valid
  } else if (e instanceof PaymentRequiredError) {
    console.error(`Payment needed: ${e.message}`);
    // Check your subscription status
  } else if (e instanceof UnsupportedMediaTypeError) {
    console.error(`Unsupported format: ${e.message}`);
    // Only raised by initTopicFromUrl
  } else if (e instanceof ServerError) {
    console.error(`Server error: ${e.message}`);
    // Retry after a delay
  }
}

from respectify import (
    RespectifyClient,
    AuthenticationError,
    BadRequestError,
    PaymentRequiredError,
    UnsupportedMediaTypeError,
    ServerError
)

client = RespectifyClient(email, api_key)

try:
    result = client.check_spam("test comment", article_id)
except AuthenticationError as e:
    print(f"Auth failed: {e}")
    # Check your email and API key
except BadRequestError as e:
    print(f"Bad request: {e}")
    # Check comment text isn't empty, article_id is valid
except PaymentRequiredError as e:
    print(f"Payment needed: {e}")
    # Check your subscription status
except UnsupportedMediaTypeError as e:
    print(f"Unsupported format: {e}")
    # Only raised by init_topic_from_url
except ServerError as e:
    print(f"Server error: {e}")
    # Retry after a delay

use Respectify\RespectifyClientAsync;
use Respectify\Exceptions\UnauthorizedException;
use Respectify\Exceptions\BadRequestException;
use Respectify\Exceptions\PaymentRequiredException;
use Respectify\Exceptions\UnsupportedMediaTypeException;
use Respectify\Exceptions\ServerException;
use Respectify\Exceptions\RespectifyException;

$client->checkSpam("test comment", $articleId)
    ->then(function ($result) {
        echo "Success: " . ($result->isSpam ? 'spam' : 'not spam');
    })
    ->otherwise(function ($e) {
        if ($e instanceof UnauthorizedException) {
            echo "Auth failed: " . $e->getMessage();
        } elseif ($e instanceof BadRequestException) {
            echo "Bad request: " . $e->getMessage();
        } elseif ($e instanceof PaymentRequiredException) {
            echo "Payment needed: " . $e->getMessage();
        } elseif ($e instanceof UnsupportedMediaTypeException) {
            echo "Unsupported format: " . $e->getMessage();
        } elseif ($e instanceof ServerException) {
            echo "Server error: " . $e->getMessage();
        } elseif ($e instanceof RespectifyException) {
            echo "API error: " . $e->getMessage();
        } else {
            throw $e;
        }
    });

$client->run();

Check the HTTP status code. Non-200 responses return the Error format:

// 401 Unauthorized
{"error": "Unauthorized", "message": "Invalid credentials", "code": 401}

// 400 Bad Request
{"error": "Bad Request", "message": "Comment cannot be empty", "code": 400}

// 402 Payment Required
{"error": "Subscription required", "message": "An active subscription is required to access this API.", "code": 402}

// 415 Unsupported Media Type
{"error": "Unsupported Media Type", "message": "Content type unsupported: image/png", "code": 415}

// 500 Internal Server Error
{"error": "Internal Server Error", "message": "An unexpected error occurred", "code": 500}

Retry Strategies

For transient errors (5xx), use exponential backoff. We recommend using established libraries rather than rolling your own:

TypeScript
Python
PHP

Use a simple retry wrapper or a library like p-retry:

import { ServerError } from "@respectify/client";

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (e) {
      if (e instanceof ServerError && attempt < maxRetries) {
        await new Promise((r) => setTimeout(r, 2 ** (attempt - 1) * 1000));
        continue;
      }
      throw e;
    }
  }
  throw new Error("Unreachable");
}

const result = await withRetry(() =>
  client.checkSpam(comment, articleId)
);

Use a retry library such as tenacity:

from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
from respectify import ServerError

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=1, max=10),
    retry=retry_if_exception_type(ServerError)
)
def check_spam_with_retry(client, comment, article_id):
    return client.check_spam(comment, article_id)

Use a promise-based retry approach with ReactPHP:

use Respectify\Exceptions\ServerException;

function withRetry($promise, $maxRetries = 3, $attempt = 1) {
    return $promise->otherwise(function ($e) use ($maxRetries, $attempt) {
        if ($e instanceof ServerException && $attempt < $maxRetries) {
            return React\Promise\Timer\sleep(pow(2, $attempt - 1))
                ->then(fn() => withRetry($promise, $maxRetries, $attempt + 1));
        }
        throw $e;
    });
}

Exception Reference​

AuthenticationError (401)​

BadRequestError (400)​

PaymentRequiredError (402)​

UnsupportedMediaTypeError (415)​

ServerError (500)​

ResponseParseError (TypeScript only)​

Error Response Format​

Basic Error Handling​

Retry Strategies​

Exception Reference

AuthenticationError (401)

BadRequestError (400)

PaymentRequiredError (402)

UnsupportedMediaTypeError (415)

ServerError (500)

ResponseParseError (TypeScript only)

Error Response Format

Basic Error Handling

Retry Strategies