Errors | Omnifence API docs

When a request fails, the API returns a JSON error object with a machine-readable code, a human-readable message, and the HTTP status code.

Error format#

JSON

{
  "error": "ERROR_CODE",
  "message": "A description of what went wrong",
  "statusCode": 400
}

Error codes#

Code	Status	Description
`INVALID_REQUEST`	400	The request is missing required fields or contains invalid values.
`BATCH_EMPTY`	400	A text moderation batch holds no item. Nothing was created or charged.
`BATCH_TOO_LARGE`	400	A text moderation batch holds more than 99 items. Nothing was created or charged.
`DUPLICATE_ITEM_KEY`	400	Two items of a text moderation batch have the same `key`. Nothing was created or charged.
`TEXT_TOO_LONG`	400	An item of a text moderation batch has a `text` longer than 20,000 characters. Nothing was created or charged.
`UNAUTHORIZED`	401	The API key is missing, invalid, or inactive.
`PAYMENT_REQUIRED`	402	Your account credit balance is at or below zero. Top up to resume submitting jobs.
`FORBIDDEN`	403	The API key is valid but lacks the scope the endpoint requires. On the Shared Registry, also returned when your membership is not active or does not allow the category.
`ACCOUNT_TERMINATED`	403	Your account has been terminated. Contact support.
`NOT_FOUND`	404	The requested resource does not exist or belongs to a different account, for example a Shared Registry entry.
`JOB_NOT_FOUND`	404	The job ID does not exist or belongs to a different account.
`BATCH_NOT_FOUND`	404	The batch ID does not exist or belongs to a different account.
`PAYLOAD_TOO_LARGE`	413	The media behind the submitted URL is larger than the limit for that endpoint (100 MB for video). No job was created and nothing was charged.
`UNSUPPORTED_MEDIA`	415	The submitted URL does not serve a supported media file, for example an HLS playlist or a DASH manifest instead of a video file.
`MEDIA_UNREACHABLE`	422	The origin refused the submitted media URL (for example HTTP 404 or 403, or an expired signed link). Fix the URL, then resubmit.
`RATE_LIMITED`	429	You have exceeded your per-client rate limit, or your daily Shared Registry check quota. See rate limiting.
`INTERNAL_ERROR`	500	An unexpected server error occurred. Retry after a short delay.
`SERVICE_UNAVAILABLE`	503	Moderation intake is busy, or a downstream dependency is temporarily unavailable. Capacity rejections carry a `Retry-After` header, in seconds.
`SUBMISSION_STATUS_UNKNOWN`	503	The submission may have been accepted, but the API could not confirm it. The body carries a `job_id`, or a `batch_id` for a text moderation batch.

Handling errors#

400: Check your request body, query parameters, or file uploads against the API reference.
401: Verify your API key is correct and active.
402: Your credit balance has hit zero or gone negative. Sign in to the dashboard and top up.
403 FORBIDDEN: Your key is missing a required scope. See scopes.
403 ACCOUNT_TERMINATED: Your account has been permanently terminated. This is not recoverable via the API.
404: Confirm the job ID is correct and was created under your account.
429: Back off and retry. Use exponential backoff with jitter.
500/503: Retry after a short delay. If the error persists, contact hello@omnifence.ai.
503 SERVICE_UNAVAILABLE: When the response carries Retry-After, wait at least that many seconds, then retry with exponential backoff and jitter.
503 SUBMISSION_STATUS_UNKNOWN: Do not resubmit immediately. The response body carries the job_id of the submission whose outcome is unknown. Poll GET /api/v1/job/{job_id}: a job that exists was accepted and is running; a JOB_NOT_FOUND means the submission was rejected and you can safely submit again. Resubmitting without polling can create a second job for the same content, and you pay for both. For a text moderation batch the body carries a batch_id instead: read GET /api/v1/moderate/text/batch/{batch_id}. A batch that exists was accepted with all its items; a BATCH_NOT_FOUND means none of its items was accepted and you can safely submit it again.