Error Response Format

All API error responses use a consistent JSON structure with three fields: error name, human-readable message, and HTTP status code.

{
  "name": "error-code-name",
  "message": "Human-readable error description",
  "status_code": "400"
}

Response Fields

nameString

Unique identifier for the error type. Use this for programmatic error handling.

messageString

Human-readable description of the error. Safe to display to end users.

status_codeString

HTTP status code as a string. Matches the actual HTTP response status.

400 Bad Request

Client errors due to invalid request data, malformed content, or validation failures.

invalid-token-format400

The API token format is invalid. Ensure you're using a valid Bearer token.

invalid-content-type400

Request Content-Type header is missing or invalid. Use application/json.

missing-field400

A required field is missing from the request body. Check the API documentation for required fields.

invalid-field-value400

A field contains an invalid value. Check field format requirements and constraints.

validation-error400

General validation error. The request data doesn't meet the required format or constraints.

invalid-schema-config400

The schema configuration is invalid or malformed.

invalid-image-format400

The image format is not supported or the image data is corrupted.

image-not-downloaded400

Could not download the image from the provided URL. Check that the URL is accessible and returns a valid image.

image-to-large400

The image at the provided URL is too large. Use a smaller image or compress the image.

content-too-large400

The request content is too large. Reduce the size of your content or images.

text-moderation-error400

Text moderation service encountered an error. Try again later or contact support if it persists.

ai-image-service-unavailable400

AI image moderation service is temporarily unavailable. Try again later.

401 Unauthorized

Authentication errors related to missing, invalid, expired, or revoked API tokens.

token-required401

API token is missing from the request. Include a valid Bearer token in the Authorization header.

invalid-token401

The provided API token is not found or invalid. Check your token and ensure it's correctly formatted.

token-expired401

The API token has expired. Generate a new token in the Console.

token-revoked401

The API token has been revoked. Generate a new token in the Console.

403 Forbidden

Permission errors due to insufficient subscription access or inactive projects.

project-inactive403

The project is not active. Check your project status in the Console.

manual-moderation-subscription-required403

Manual moderation access is required. Upgrade to a manual moderation subscription.

automated-moderation-subscription-required403

Automated moderation access is required. Upgrade your subscription or check your free trial usage.

404 Not Found

Resource not found errors when the requested resource doesn't exist or isn't accessible.

project-not-found404

The specified project was not found or you don't have access to it.

schema-not-found404

The specified schema was not found in your project. Check the schema ID and ensure it exists.

submission-not-found404

The specified submission was not found. Check the submission ID.

moderation-request-not-found404

The moderation request was not found. This may occur if the request was already processed or removed.

resource-not-found404

The requested resource was not found. Check the endpoint URL and resource ID.

409 Conflict

Request conflicts with the current state of the resource.

request-already-processed409

The request has already been processed and cannot be modified. This prevents duplicate processing.

422 Unprocessable Entity

Request is well-formed but cannot be processed due to business logic constraints.

unsupported-moderation-type422

The requested moderation type is not supported for this schema or content.

appeal-not-allowed422

Appeals are not allowed for this submission. This may be due to submission status or appeal limits.

500 Internal Server Error

Unexpected server errors. These should be rare and are automatically logged for investigation.

internal-server-error500

An unexpected internal server error occurred. This includes timeouts, processing failures, and other server-side issues. Contact support if this persists.

Error Handling Best Practices

✅ Use Error Names

Always check the name field for programmatic error handling rather than parsing messages.

✅ Implement Retry Logic

Retry requests for 5xx errors with exponential backoff. Don't retry 4xx errors without fixing the request.

✅ Log Error Details

Log both the error name and message for debugging. Messages are safe to display to users.

❌ Don't Ignore Status Codes

Always check HTTP status codes in addition to error names for proper error categorization.

Ready to Get Started?

Implement robust error handling in your application with our comprehensive error codes.

Authentication API

Handle authentication errors

→

Automated Moderation API

Handle moderation errors

→

Error Codes