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)

Python

AuthenticationError

PHP

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)

Python

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

PHP

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)

Python

PaymentRequiredError

PHP

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)

Python

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.

PHP

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)

Python

ServerError

PHP

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.

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

Python

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

PHP

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();

REST API

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:

Python

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)

PHP

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;
    });
}