> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnifence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common integration problems

## Authentication issues

### `401 UNAUTHORIZED`

**Cause**: The API key is missing, malformed, or has been revoked.

**Fix**:

* Confirm the `Authorization` header uses the exact format: `Bearer YOUR_API_KEY`
* Check that the key has not been revoked in the [dashboard](https://app.omnifence.ai)
* Ensure the key belongs to an active account

```bash theme={null}
# Test your key with a minimal moderation request
curl -X POST https://api.omnifence.ai/api/v1/moderate/prompt \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"hello"}'
```

### `403 ACCOUNT_TERMINATED`

**Cause**: Your account has been terminated by an administrator, typically after a manual review of policy violations. See [account termination](/authentication#account-termination).

**Fix**: Contact support at [support@omnifence.ai](mailto: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`.

```bash theme={null}
# Correct: image included
curl -X POST https://api.omnifence.ai/api/v1/moderate/image \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=https://example.com/photo.jpg"
```

### 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**:

1. **No webhook registered**: Call `POST /api/v1/webhook/register` with your URL, or include `webhook_url` in the moderation request.
2. **Webhook URL is HTTP**: The API requires HTTPS. Use an HTTPS endpoint.
3. **Your server timed out**: Webhook delivery has a 10-second timeout. Confirm your server responds within that window. See [webhook reliability](/platform/webhook-reliability).
4. **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](/platform/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](/platform/rate-limiting).

**Fix**: Reduce request frequency or implement exponential backoff. See [error recovery](/platform/error-recovery#rate-limit-recovery) for a retry example.

***

## Still stuck?

Contact support at [support@omnifence.ai](mailto:support@omnifence.ai) with your `job_id` and the API response body.