Authentication issues
401 UNAUTHORIZED
Cause: The API key is missing, malformed, or has been revoked.
Fix:
- Confirm the
Authorizationheader uses the exact format:Bearer YOUR_API_KEY - Check that the key has not been revoked in the dashboard
- Ensure the key belongs to an active account
403 ACCOUNT_TERMINATED
Cause: Your account has been terminated by an administrator, typically after a manual review of policy violations. See account termination.
Fix: Contact support at support@omnifence.ai. This state cannot be resolved through the API.
Submission failures
400 INVALID_REQUEST — missing fields
Cause: The required field for the endpoint was missing — image for /moderate/image,
text for /moderate/prompt, or video for /moderate/video.
Fix: Include the field. For /moderate/image, pass a publicly reachable image.
Using the wrong endpoint for your media type
Cause: Each modality has its own endpoint./moderate/image accepts an image,
/moderate/prompt accepts a text prompt, and /moderate/video accepts a video. Submitting an
image to the prompt endpoint (or vice versa) returns 400 INVALID_REQUEST.
Fix: Use the endpoint that matches your media type.
400 INVALID_REQUEST — “image file upload is currently disabled”
Cause: Direct image file uploads to /moderate/image are paused. Only image is accepted.
Fix: Host the image at a publicly reachable URL and pass it as the image field.
400 INVALID_REQUEST — “video file upload is currently disabled”
Cause: Direct video file uploads to /moderate/video are paused. Only video is accepted.
Fix: Host the video at a publicly reachable URL and pass it as the video field.
Video job fails — video too large or unreachable
Cause: The video field points to a file larger than 300 MB, or the worker could not download it.
The submission still returns 202, but the job later ends with status: "failed".
Fix: Host a video under 300 MB at a publicly reachable HTTP or HTTPS URL. URLs that resolve to a
private or internal address — or use a non-HTTP scheme — are rejected at submission with
400 INVALID_REQUEST.
Image job fails — image unreachable
Cause: The classifiers could not fetch the image URL. The submission still returns 202, but
the job later ends with status: "failed".
Fix: Host the image at a publicly reachable HTTP or HTTPS URL. URLs that resolve to a private or
internal address — or use a non-HTTP scheme — are rejected at submission with 400 INVALID_REQUEST.
Webhook issues
Webhook is not receiving events
Possible causes and fixes:- No webhook registered: Call
POST /api/v1/webhook/registerwith your URL, or includewebhook_urlin the moderation request. - Webhook URL is HTTP: The API requires HTTPS. Use an HTTPS endpoint.
- Your server timed out: Webhook delivery has a 10-second timeout. Confirm your server responds within that window. See webhook reliability.
- Server returned non-
2xx: The API logs failures but does not retry. Check your server logs.
Webhook fired but the payload looks wrong
Fix: Verify you are reading the correct fields. The webhook payload format depends on the moderation type — see webhooks for the full schema.Job issues
Job is stuck in processing
Cause: Processing times vary. Prompt and image moderation typically complete in seconds; video moderation for long clips may take longer.
Fix: Poll the job status endpoint. If the job has been processing for more than 10 minutes, resubmit and contact support if the issue persists.
404 JOB_NOT_FOUND
Cause: Either the job ID is incorrect, or the job belongs to a different client account. Jobs are scoped per account.
Fix: Confirm the job_id matches one returned by your account’s submission.
is_prohibited is null
Cause: The job has not yet completed (status is queued or processing), or it failed (status is failed).
Fix: Wait for status: "completed" before reading is_prohibited. For failed jobs, resubmit the request.
Rate limiting
429 RATE_LIMITED
Cause: You have exceeded your account’s request rate. See rate limiting.
Fix: Reduce request frequency or implement exponential backoff. See error recovery for a retry example.
Still stuck?
Contact support at support@omnifence.ai with yourjob_id and the API response body.